# 1MCP Agent - Complete Documentation

> 1MCP is a Model Context Protocol proxy that aggregates capabilities from multiple MCP servers into a unified interface, enabling AI assistants to connect to multiple tools and services through a single connection. This comprehensive documentation covers installation, configuration, server management, security, and advanced deployment scenarios.

## Overview

1MCP Agent serves as a centralized proxy for Model Context Protocol (MCP) servers, allowing AI assistants to seamlessly connect to multiple tools, databases, and services through a single connection point. It supports both HTTP/SSE and STDIO transports, provides comprehensive server management capabilities, and includes advanced features like server filtering, preset management, and health monitoring.

## Getting Started

### Installation Options

#### Binary Installation
Download the latest release from GitHub releases and add to your system PATH.

#### NPM Installation
```bash
npm install -g @1mcp/agent
```

#### Development Setup
```bash
git clone https://github.com/1mcp-app/agent.git
cd agent
pnpm install
pnpm build
```

### Quick Start Configuration

Create a basic configuration file to add MCP servers:
```bash
1mcp mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
```

Start the proxy server:
```bash
1mcp serve --port 3051
```

## Core Features

### Server Management

#### Adding Servers
```bash
# Add MCP servers from the registry
1mcp mcp add filesystem
1mcp mcp add database

# Add custom servers with commands
1mcp mcp add custom-server -- npx -y @your/custom-server
```

#### Server Operations
- **Add/Remove**: Dynamically add or remove MCP servers
- **Enable/Disable**: Temporarily enable or disable servers without removing configuration
- **Install/Uninstall**: Install packages from the MCP registry or uninstall them
- **Update**: Update servers to latest versions
- **Status**: Check server health and connectivity status

#### Server Configuration
- **Command-based servers**: Execute external processes with custom commands
- **Registry-based servers**: Install and manage from MCP registry
- **Tag-based filtering**: Organize servers with tags for selective access
- **Environment variables**: Configure server-specific environment settings

### Application Management

#### Backup and Restore
```bash
# Backup current configuration
1mcp app backup /path/to/backup.json

# Restore from backup
1mcp app restore /path/to/backup.json
```

#### Consolidation
- **App Discovery**: Automatically discover and consolidate MCP applications
- **Configuration Merging**: Merge multiple configurations into unified setup

### Preset Management

#### Configuration Presets
```bash
# Create new preset
1mcp preset create development

# Edit preset configuration
1mcp preset edit development

# Test preset configuration
1mcp preset test development

# Select active preset
1mcp preset select development
```

#### Preset Features
- **Environment-specific configurations**: Separate presets for development, staging, production
- **Server groups**: Organize servers into logical groups
- **Configuration testing**: Validate preset configurations before deployment

### Registry Integration

#### MCP Registry
```bash
# Search available MCP servers
1mcp registry search filesystem
1mcp registry search database

# Install from registry
1mcp mcp install @modelcontextprotocol/server-filesystem
```

## CLI Commands Reference

### MCP Commands

#### Server Management
- `1mcp mcp add <name> [command]`: Add new MCP server
- `1mcp mcp remove <name>`: Remove configured server
- `1mcp mcp list`: List all configured servers
- `1mcp mcp status [name]`: Check server status and health
- `1mcp mcp enable <name>`: Enable a disabled server
- `1mcp mcp disable <name>`: Disable a server temporarily

#### Package Management
- `1mcp mcp install <package>`: Install package from MCP registry
- `1mcp mcp uninstall <name>`: Uninstall and remove server
- `1mcp mcp update <name>`: Update server to latest version
- `1mcp mcp search <query>`: Search MCP registry

### App Commands

#### Configuration Management
- `1mcp app backup <path>`: Backup current configuration
- `1mcp app restore <path>`: Restore configuration from backup
- `1mcp app status`: Show application status and information

#### Discovery and Consolidation
- `1mcp app discover <path>`: Discover MCP applications in directory
- `1mcp app consolidate`: Consolidate discovered applications
- `1mcp app list`: List discovered applications

### Preset Commands

#### Preset Management
- `1mcp preset create <name>`: Create new configuration preset
- `1mcp preset delete <name>`: Delete existing preset
- `1mcp preset edit <name>`: Edit preset configuration
- `1mcp preset list`: List all available presets
- `1mcp preset select <name>`: Select active preset
- `1mcp preset show [name]`: Show preset details
- `1mcp preset test <name>`: Test preset configuration

### Registry Commands

#### Registry Operations
- `1mcp registry search <query>`: Search MCP registry for servers
- `1mcp registry info <package>`: Get detailed package information

### Serve and Proxy Commands

#### Server Operations
- `1mcp serve`: Start HTTP proxy server
- `1mcp serve --port <port>`: Specify custom port
- `1mcp serve --host <host>`: Bind to specific host
- `1mcp proxy`: Start in proxy mode

## Advanced Configuration

### Configuration Structure

#### Global Configuration
Configuration is stored in JSON format with the following main sections:
- **servers**: MCP server configurations
- **proxy**: HTTP proxy settings
- **logging**: Log configuration
- **auth**: Authentication settings

#### Server Configuration
Each server configuration includes:
- **command**: Server execution command
- **args**: Command arguments
- **env**: Environment variables
- **tags**: Server tags for filtering
- **disabled**: Enable/disable flag

### Environment Variables

#### Core Configuration
- `ONE_MCP_CONFIG_DIR`: Configuration directory path
- `ONE_MCP_LOG_LEVEL`: Logging level (debug, info, warn, error)
- `ONE_MCP_PORT`: Default server port (default: 3051)
- `ONE_MCP_HOST`: Default server host (default: localhost)

#### Development Variables
- `ONE_MCP_LOG_FILE`: Log file path
- `ONE_MCP_ENABLE_AUTH`: Enable authentication
- `ONE_MCP_ENABLE_ASYNC_LOADING`: Enable async server loading

### Performance Optimization

#### Server Loading
- **Async Loading**: Orchestrate slow-starting servers gracefully
- **Health Monitoring**: Continuous server health checks
- **Connection Management**: Efficient connection pooling and reuse

#### Resource Management
- **Memory Optimization**: Streaming for large responses
- **Process Management**: Proper cleanup of child processes
- **Resource Monitoring**: Track resource usage and limits

### Developer Tools
- **IDE Integration**: Support for various development environments
- **HTTP Transport**: Web-based client connections
- **Tag-based Access**: Filter servers based on client requirements
- **Real-time Updates**: Dynamic capability updates

## Architecture

### System Components

#### Core Components
- **ServerManager**: MCP server lifecycle management and health monitoring
- **TransportFactory**: Protocol-specific transport creation (HTTP, STDIO)
- **CapabilitiesManager**: Dynamic capability aggregation across servers
- **McpConfigManager**: Configuration management with hot-reload support

#### Transport Layer
- **HTTP/SSE Transport**: Multi-client support via Server-Sent Events
- **STDIO Transport**: Direct MCP protocol communication
- **Connection Management**: Connection pooling and multiplexing

### Design Patterns

#### Singleton Pattern
- **ServerManager**: Centralized server instance management
- **McpConfigManager**: Global configuration management
- **AgentConfigManager**: Application-wide settings

#### Factory Pattern
- **TransportFactory**: Protocol-specific transport instantiation
- **Configuration Parser**: Format-specific configuration parsing

## Security Features

### Access Control
- **Tag-based Filtering**: Control server access based on client tags
- **Scope-based Authorization**: Fine-grained permission control
- **Environment Variable Protection**: Secure handling of sensitive environment data

### Configuration Security
- **Validation**: Schema-based configuration validation
- **Hot Reload Security**: Safe configuration updates without service interruption
- **Process Isolation**: Isolated server processes for security

## Deployment

### Development Environment
```bash
# Start development server with hot reload
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build
```

### Production Deployment

#### Docker Deployment
```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install -g @1mcp/agent
EXPOSE 3051
CMD ["1mcp", "serve", "--port", "3051"]
```

#### Service Configuration
- **Process Management**: Use PM2 or similar for process management
- **Reverse Proxy**: Nginx or Apache reverse proxy configuration
- **SSL/TLS**: HTTPS termination for secure connections
- **Monitoring**: Health check endpoints and logging

## Monitoring and Observability

### Health Monitoring
- **Health Endpoints**: Built-in health check endpoints
- **Server Status**: Real-time server connectivity monitoring
- **Performance Metrics**: Resource usage and response times

### Logging
- **Structured Logging**: Winston-based logging with metadata
- **Log Levels**: Configurable log levels (debug, info, warn, error)
- **Conditional Logging**: Performance-optimized conditional logging
- **Log Rotation**: Automatic log file rotation and archival

## Troubleshooting

### Common Issues

#### Connection Problems
- Server startup failures and configuration errors
- Network connectivity and firewall issues
- Port conflicts and binding problems

#### Configuration Issues
- Invalid JSON syntax and missing required fields
- Environment variable conflicts and file permissions
- Server command and argument configuration errors

### Debug Tools

#### Built-in Diagnostics
- **Status Commands**: `1mcp app status`, `1mcp mcp status`
- **Configuration Validation**: Check configuration syntax and validity
- **Health Checks**: Verify server connectivity and responsiveness

#### Debug Logging
```bash
# Enable debug logging
ONE_MCP_LOG_LEVEL=debug 1mcp serve

# Log to specific file
ONE_MCP_LOG_FILE=./debug.log 1mcp serve
```

## Reference Documentation

### Technical References
- **Architecture**: Detailed system design and component interaction
- **Security**: Security implementation details and best practices
- **Internal Tools**: Discovery, installation, and management tools
- **Health Check**: Health monitoring endpoint documentation
- **MCP Servers**: MCP server configuration and management
- **Feature Comparison**: Version differences and capability comparisons

### Configuration Reference
- **Core Features**: Detailed feature documentation
- **Essentials**: Core configuration and management
- **Advanced Topics**: Enterprise, performance, and security configurations
- **Integration Guides**: Client integration and setup instructions

## Contributing

### Development Workflow
1. Fork the repository
2. Create feature branch from main
3. Implement changes with comprehensive tests
4. Update documentation as needed
5. Submit pull request for review

### Code Quality Standards
- **TypeScript**: Strict type safety and comprehensive type definitions
- **Testing**: High test coverage with unit and integration tests
- **Code Style**: ESLint and Prettier for consistent formatting
- **Documentation**: Comprehensive API documentation and examples

## Support and Community

### Getting Help
- **GitHub Issues**: Report bugs and request features
- **Documentation**: Comprehensive guides and reference documentation
- **Community**: Discussion forums and community support

### Resources
- **Repository**: https://github.com/1mcp-app/agent
- **Documentation**: https://docs.1mcp.app
- **MCP Specification**: Model Context Protocol documentation
- **Registry**: MCP server registry and ecosystem
