1MCP System Architecture

Vision: A unified, reliable proxy that makes multiple MCP servers appear as one, simplifying AI assistant integration while maintaining security and performance.

🎯 Purpose & Context

Problem: AI assistants need to connect to multiple MCP servers, but managing dozens of individual connections is complex, unreliable, and security-intensive.

Solution: 1MCP acts as a unified proxy/multiplexer that aggregates multiple MCP servers behind a single, reliable interface.

Success Metrics:

• Reliability: Stable operation with proper error handling
• Performance: Efficient request forwarding to backend servers
• Security: OAuth 2.1 authentication and secure defaults
• Simplicity: Single configuration file, easy deployment

📏 System Constraints

Hard Constraints

• Single Binary: Must deploy as one executable, no external dependencies
• MCP Protocol: Must be 100% compatible with MCP Latest specification
• Stdio Transport: Backend servers communicate via stdio or streamable http (security boundary)
• Configuration: All config via single JSON file, hot-reloadable

Soft Constraints

• Concurrent Connections: Handle multiple simultaneous client connections
• Backend Servers: Support multiple MCP servers per instance
• Network: Works behind corporate firewalls (HTTP/SSE only)
• Startup Time: Fast startup for development iterations
• Dependencies: Minimal external dependencies for security

Why These Constraints

• Single Binary: Enterprise deployment requirement - no complex setup
• Multi-Transport: Backend servers support stdio, HTTP, and streamable HTTP transports
• Hot Reload: Zero-downtime configuration updates required

🏗️ Architectural Principles

Principle 1: Reliability Over Performance

• System must stay operational even if individual backends fail
• Graceful degradation preferred over fast failure
• Connection management with retry logic and timeouts

Principle 2: Security by Default

• All endpoints require authentication unless explicitly disabled
• Backend servers run in isolated processes with secure transport protocols
• Input sanitization on all external data
• No sensitive data in logs

Principle 3: Simplicity Over Flexibility

• Single deployment model, not configurable
• Convention over configuration where possible
• Explicit rather than implicit behavior

Principle 4: Transparency to Clients

• MCP protocol compliance - clients don't know it's a proxy
• Error messages preserve backend server context
• No protocol modifications or extensions

🔄 Decision Framework

When evaluating new features or changes, ask:

Reliability Questions

• Does this reduce system availability?
• What happens if this component fails?
• Can the system continue operating without it?

Security Questions

• Does this expand the attack surface?
• Could this leak sensitive information?
• Are we maintaining defense in depth?

Simplicity Questions

• Does this add configuration complexity?
• Will this make deployment harder?
• Can we solve this with existing patterns?

Compatibility Questions

• Does this break MCP protocol compliance?
• Will existing clients continue to work?
• Are we preserving backend server interfaces?

📊 Quality Attribute Scenarios

Reliability Scenario

• Situation: Backend MCP server crashes during request processing
• Response: System detects failure, marks server unavailable, retries request on other servers if applicable
• Measure: <5 second recovery, client receives appropriate error, system remains available
• Current: Connection pooling with health checks, exponential backoff retry

Security Scenario

• Situation: Client attempts to access MCP server without proper authorization
• Response: OAuth token validation, scope checking, request denied with 403
• Measure: Zero unauthorized access, all attempts logged with client context
• Current: OAuth 2.1 with scope-based authorization, session management

Performance Scenario

• Situation: Multiple concurrent clients making requests to backend servers
• Response: Efficient request forwarding, proper error handling, async processing
• Measure: Reliable request processing, system remains responsive
• Current: Express.js with proper error handling, async request forwarding

Maintainability Scenario

• Situation: New MCP server added to configuration file
• Response: Hot reload detects change, spawns new server process, updates routing
• Measure: <30 seconds to become available, zero downtime
• Current: File system watching with debounced reload, graceful process management

🚫 System Boundaries & Anti-Patterns

What We Are

• MCP Protocol Proxy: Faithful implementation of MCP specification
• Authentication Gateway: OAuth 2.1 security layer
• Connection Multiplexer: Many clients to many servers
• Process Manager: Lifecycle management for backend servers

What We Are NOT

• Business Logic Engine: No data transformation or business rules
• Caching Layer: Every request goes to backend (for now)
• Service Mesh: Not a general-purpose service communication layer
• Database: No persistent storage of application data

Integration Boundaries

Anti-Patterns We Avoid

• Shared Database: No shared state between instances
• Network Dependencies: No calls to external services at runtime
• Protocol Extensions: No MCP protocol modifications
• Synchronous Chains: No blocking calls in request path
• Global State: All state is request-scoped or configuration

🗺️ Evolution Strategy

Phase 1: Single Instance Proxy (Current)

• Scope: One 1MCP instance per deployment
• Features: HTTP/SSE transport, OAuth, basic connection pooling
• Constraints: No horizontal scaling, local configuration only

Phase 2: Enhanced Features (Future)

• Scope: Additional operational features based on user feedback
• Features: Enhanced monitoring, advanced configuration options
• Migration: Backward compatible, optional enhancements

Phase 3: Advanced Capabilities (Future)

• Scope: Advanced features for enterprise use cases
• Features: Enhanced security, operational improvements
• Migration: Configuration extensions, no protocol changes

Evolution Principles

• Backward Compatibility: Existing deployments continue working
• Progressive Enhancement: New features are opt-in
• Zero Downtime: All migrations support hot upgrades
• Configuration Driven: Features enabled through configuration

⚡ Architecture Validation

Automated Architecture Testing

// Example: Architecture tests enforce our boundaries describe('Architecture Constraints', () => {  test('No business logic in transport layer', () => {  // Static analysis ensures transport only handles HTTP/auth  });   test('All external calls use circuit breakers', () => {  // Validate resilience patterns are used  });   test('No direct database access outside repositories', () => {  // Enforce data access patterns  }); });

Architecture Metrics

• Dependency Violations: 0 (enforced by tests)
• Cyclomatic Complexity: <10 per function (linting)
• Security Scan: 0 high/critical vulnerabilities
• API Compatibility: 100% MCP protocol compliance
• Test Coverage: >90% for critical paths

Continuous Validation

• Architecture tests run in CI/CD pipeline
• Dependency analysis in pull requests
• Security scanning on every build
• Performance regression testing

🔍 Observability & Monitoring

Health Indicators

• System Health: All core components operational
• Backend Health: Individual MCP server status
• Connection Health: Client connection pool status
• Configuration Health: Config file validity and reload status

Key Metrics

• Availability: System uptime percentage
• Latency: Request response time distribution
• Throughput: Requests per second capacity
• Error Rate: Failed requests percentage
• Resource Usage: Memory, CPU, connection counts

Monitoring Indicators

• Critical: System unavailable, authentication failures, configuration errors
• Warning: Backend server disconnections, repeated request failures
• Info: Configuration reloaded, new client connections, successful operations

🚨 Failure Modes & Recovery

Failure Categories

Backend Server Failures

• Symptoms: Process crash, unresponsive, invalid responses
• Detection: Health checks, request timeouts, error patterns
• Recovery: Process restart, connection retry, graceful degradation
• Escalation: Remove from rotation, alert operators

Configuration Failures

• Symptoms: Invalid JSON, missing servers, permission errors
• Detection: File parsing errors, validation failures
• Recovery: Retain previous valid configuration, log errors
• Escalation: Disable hot-reload, require manual intervention

Resource Exhaustion

• Symptoms: High memory usage, connection limits hit, slow responses
• Detection: Resource monitoring, performance degradation
• Recovery: Connection throttling, graceful degradation, load shedding
• Escalation: Service restart, horizontal scaling

Security Breaches

• Symptoms: Authentication bypass, unauthorized access, token leakage
• Detection: Security monitoring, anomaly detection, audit logs
• Recovery: Immediate service isolation, token revocation, forensic analysis
• Escalation: Complete service shutdown, incident response procedures

Recovery Expectations

• Backend Reconnection: Automatic with retry logic
• Configuration Reload: Immediate detection and application
• Security Incident: Immediate authentication failure response
• System Recovery: Restart and reload as needed

🏗️ Code Structure & Organization

Project Layout

The codebase follows a layered architecture with clear separation of concerns:

src/ ├── application/ # Application-level services │ └── services/ # Cross-cutting orchestration services │ ├── configReloadService.ts │ ├── healthService.ts │ └── tokenEstimationService.ts ├── auth/ # Authentication & authorization │ ├── storage/ # Repository pattern for auth data │ ├── sdkOAuthClientProvider.ts │ ├── sdkOAuthServerProvider.ts │ └── sessionTypes.ts ├── commands/ # CLI command implementations │ ├── app/ # App management commands │ ├── mcp/ # MCP server management commands │ ├── preset/ # Preset management commands │ ├── proxy/ # Proxy commands │ ├── serve/ # Server commands │ └── shared/ # Shared command utilities ├── config/ # Configuration management │ ├── configContext.ts │ ├── mcpConfigManager.ts │ ├── envProcessor.ts │ ├── projectConfigLoader.ts │ └── projectConfigTypes.ts ├── constants/ # Domain-organized constants │ ├── api.ts # API endpoints, ports, hosts │ ├── auth.ts # Authentication constants │ ├── mcp.ts # MCP protocol constants │ ├── paths.ts # File paths, directories │ └── index.ts # Barrel export ├── core/ # Core business logic │ ├── capabilities/ # MCP capability management │ ├── client/ # Client management │ ├── filtering/ # Request filtering logic │ ├── instructions/ # Template engine │ ├── loading/ # Async loading orchestration │ ├── notifications/ # Notification system │ ├── protocol/ # Protocol message handlers │ ├── server/ # Server lifecycle management │ └── types/ # Shared type definitions ├── domains/ # Domain modules │ ├── backup/ # Backup management domain │ ├── discovery/ # App discovery domain │ ├── preset/ # Preset management domain │ │ ├── manager/ # PresetManager │ │ ├── parsers/ # Tag query parsing │ │ ├── services/ # Preset services │ │ └── types/ # Preset types │ └── registry/ # MCP Registry domain │ ├── formatters/ # Registry-specific formatters │ ├── cacheManager.ts # Registry caching │ ├── mcpRegistryClient.ts # Registry client │ ├── mcpToolSchemas.ts # Registry schemas │ ├── searchFiltering.ts # Registry search │ └── types.ts # Registry types ├── logger/ # Logging infrastructure │ ├── configureGlobalLogger.ts │ └── [6 other logger files] ├── transport/ # Transport layer implementations │ ├── http/ # HTTP/SSE transport │ │ ├── middlewares/ # Express middlewares │ │ └── routes/ # API route handlers │ └── [5 transport files] └── utils/ # Generic utilities  ├── core/ # Core utilities  ├── ui/ # CLI utilities  └── validation/ # Input validation

Architectural Layers

1. Application Layer (application/)

• Purpose: Cross-cutting orchestration services
• Responsibilities: Configuration reloading, health monitoring, token estimation
• Dependencies: Can depend on core and domains
• Examples: configReloadService, healthService

2. Core Layer (core/)

• Purpose: Core business logic and domain entities
• Responsibilities: MCP protocol handling, capability management, server lifecycle
• Dependencies: Should not depend on application layer
• Examples: ServerManager, ClientManager, CapabilityManager

3. Domain Layer (domains/)

• Purpose: Self-contained business domains
• Responsibilities: Specific business logic (presets, discovery, backup, registry)
• Dependencies: Can depend on core, should be independent
• Examples: PresetManager, BackupManager, AppDiscovery, McpRegistryClient

4. Transport Layer (transport/)

• Purpose: Protocol implementations and communication
• Responsibilities: HTTP/SSE, STDIO, message routing
• Dependencies: Can depend on core and application
• Examples: ExpressServer, StdioTransport

5. Infrastructure Layer (auth/, config/, logger/)

• Purpose: Cross-cutting infrastructure concerns
• Responsibilities: Authentication, configuration, logging
• Dependencies: Minimal dependencies, used by all layers
• Examples: McpConfigManager, OAuthClientProvider

Design Principles

Domain-Driven Design

• Domains: Self-contained modules with clear boundaries
• Services: Application-level orchestration
• Core: Shared business logic and entities

Dependency Direction

Application → Core → Domains  ↓ ↓ Transport → Infrastructure

File Organization

• Co-location: Related files grouped together
• Barrel Exports: Clean import paths with index.ts
• Domain Boundaries: Clear ownership and responsibilities

Naming Conventions

• Managers: *Manager.ts for stateful services
• Services: *Service.ts for stateless operations
• Types: *Types.ts for type definitions
• Utils: Generic utilities only

Migration Benefits

The restructured codebase provides:

• 57% reduction in utils files (47 → 20)
• Clear domain boundaries with dedicated modules
• Better maintainability through organized structure
• Improved scalability with independent domains
• Enhanced developer experience with clear file locations

How It Works

1MCP acts as a proxy, managing and aggregating multiple MCP servers. It starts and stops these servers as subprocesses and forwards requests from AI assistants to the appropriate server. This architecture allows for a single point of entry for all MCP traffic, simplifying management and reducing overhead.

System Architecture

Request Flow

---

This architecture serves as our decision-making framework. When in doubt, refer back to our principles and constraints. All changes should strengthen these foundations, not weaken them.