mcpctl/docs/architecture.md

mcpctl Architecture

Overview

mcpctl is a kubectl-like management tool for MCP (Model Context Protocol) servers. It consists of a CLI, a daemon server, a database layer, a local proxy, and shared utilities.

Package Structure

src/
├── cli/          @mcpctl/cli          - Command-line interface
├── mcpd/         @mcpctl/mcpd         - Daemon server (REST API)
├── db/           @mcpctl/db           - Database layer (Prisma + PostgreSQL)
├── local-proxy/  @mcpctl/local-proxy  - MCP protocol proxy
└── shared/       @mcpctl/shared       - Shared constants and utilities

Component Diagram

┌─────────────────┐     HTTP      ┌──────────────┐     Prisma     ┌────────────┐
│   mcpctl CLI    │ ──────────────│    mcpd      │ ──────────────│ PostgreSQL │
│  (Commander.js) │               │  (Fastify 5) │               │            │
└─────────────────┘               └──────┬───────┘               └────────────┘
                                         │
                                         │ Docker/Podman API
                                         ▼
                                  ┌──────────────┐
                                  │  Containers  │
                                  │ (MCP servers)│
                                  └──────────────┘

┌─────────────────┐    STDIO     ┌──────────────┐    STDIO/HTTP   ┌────────────┐
│  Claude / LLM   │ ────────────│  local-proxy  │ ──────────────│ MCP Servers│
│                 │              │  (McpRouter)  │               │            │
└─────────────────┘              └──────────────┘               └────────────┘

CLI (@mcpctl/cli)

The CLI is built with Commander.js and communicates with mcpd via HTTP REST.

Commands

Command	Description
mcpctl get <resource>	List resources (servers, profiles, projects, instances)
mcpctl describe <resource> <id>	Show detailed resource info
mcpctl apply <file>	Apply declarative YAML/JSON configuration
mcpctl setup [name]	Interactive server setup wizard
mcpctl instance list/start/stop/restart/remove/logs/inspect	Manage instances
mcpctl claude generate/show/add/remove	Manage .mcp.json files
mcpctl project list/create/delete/show/profiles/set-profiles	Manage projects
mcpctl config get/set/path	Manage CLI configuration
mcpctl status	Check daemon connectivity

Configuration

CLI config is stored at ~/.config/mcpctl/config.json with:

• daemonUrl: mcpd server URL (default: http://localhost:4444)

Daemon (@mcpctl/mcpd)

Fastify 5-based REST API server that manages MCP server lifecycle.

Layers

1. Routes - HTTP handlers, parameter extraction
2. Services - Business logic, validation (Zod schemas), error handling
3. Repositories - Data access via Prisma (interface-based for testability)

API Endpoints

Endpoint	Methods	Description
/api/v1/servers	GET, POST	MCP server definitions
/api/v1/servers/:id	GET, PUT, DELETE	Single server operations
/api/v1/profiles	GET, POST	Server configuration profiles
/api/v1/profiles/:id	GET, PUT, DELETE	Single profile operations
/api/v1/projects	GET, POST	Project management
/api/v1/projects/:id	GET, PUT, DELETE	Single project operations
/api/v1/projects/:id/profiles	GET, PUT	Project profile assignments
/api/v1/projects/:id/mcp-config	GET	Generate .mcp.json
/api/v1/instances	GET, POST	Instance lifecycle
/api/v1/instances/:id	GET, DELETE	Instance operations
/api/v1/instances/:id/stop	POST	Stop instance
/api/v1/instances/:id/restart	POST	Restart instance
/api/v1/instances/:id/inspect	GET	Container inspection
/api/v1/instances/:id/logs	GET	Container logs
/api/v1/audit-logs	GET	Query audit logs
/api/v1/audit-logs/:id	GET	Single audit log
/api/v1/audit-logs/purge	POST	Purge expired logs
/health	GET	Health check (detailed)
/healthz	GET	Liveness probe

Container Orchestration

The McpOrchestrator interface abstracts container management:

• DockerContainerManager - Docker/Podman implementation via dockerode
• Future: KubernetesOrchestrator for k8s deployments

Local Proxy (@mcpctl/local-proxy)

Aggregates multiple MCP servers behind a single STDIO endpoint.

Features

• Tool namespacing: servername/toolname routing
• Resource forwarding: resources/list and resources/read
• Prompt forwarding: prompts/list and prompts/get
• Notification pass-through: Upstream notifications forwarded to client
• Health monitoring: Periodic health checks with state tracking
• Transport support: STDIO (child process) and HTTP (SSE/Streamable HTTP)

Usage

# Via config file
mcpctl-proxy --config proxy.json

# Via CLI flags
mcpctl-proxy --upstream "slack:npx -y @anthropic/slack-mcp" \
             --upstream "github:npx -y @anthropic/github-mcp"

Database (@mcpctl/db)

Prisma ORM with PostgreSQL. Key models:

• User / Session - Authentication
• McpServer - Server definitions (name, transport, package, docker image)
• McpProfile - Per-server configurations (env overrides, permissions)
• Project - Grouping of profiles for a workspace
• McpInstance - Running container instances with lifecycle state
• AuditLog - Immutable operation audit trail

Shared (@mcpctl/shared)

Constants and utilities shared across packages:

• APP_NAME, APP_VERSION
• Common type definitions

Design Principles

1. Interface-based repositories - All data access through interfaces for testability
2. Dependency injection - Services receive dependencies via constructor
3. Zod validation - All user input validated with Zod schemas
4. Namespaced errors - Custom error classes with HTTP status codes
5. TypeScript strict mode - exactOptionalPropertyTypes, noUncheckedIndexedAccess