mcp-compose

Run MCP servers once, share them across Claude Code, Codex, and DeepSeek Harness sessions.

Claude Code launches stdio MCP servers per session by default. mcp-compose converts them to persistent HTTP endpoints using a built-in gateway and manages them with pm2, so multiple sessions can connect to the same running servers.

Servers run directly on your system without containerization, preserving full access to local dependencies that some MCP servers require.

Installation

No installation required - use npx. (RECOMMENDED)

npx -y mcp-compose status

You can add an alias to ~/.bashrc or ~/.zshrc:

alias mcp-compose='npx -y mcp-compose'

Or install globally:

npm install -g mcp-compose

Quick Start

mcp-compose up       # Create a template if no config exists, then exit
# Edit mcp-compose.json and enable the servers and vendor sync targets you want
mcp-compose up       # Start enabled servers and sync enabled vendors
mcp-compose status   # Check status
mcp-compose down     # Stop servers

Configuration

mcp-compose up creates mcp-compose.json in the current directory if no configuration is found. It uses the packaged config.sample.json template with all example servers and all three vendor sync targets set to disabled: true, then exits without starting processes or syncing client configs. Remove disabled: true or change it to false for the servers and vendors you want to enable.

Existing configuration is never overwritten. The search checks ~/.config/mcp-compose/ before the current directory and accepts JSON or JSONC. An explicit --config path must already exist; a missing explicit path is an error. status, down, restart, and logs do not create templates.

Full Configuration Reference

{
  "settings": {
    "portBase": 19100,
    "claude": {
      "disabled": true,
      "configPath": "~/.mcp.json"
    },
    "codex": {
      "disabled": true,
      "configPath": "~/.codex/config.toml"
    },
    "dsh": {
      "disabled": true,
      "home": "~/.dsh",
      "profiles": ["web"]
    },
    "logLevel": "info"
  },
  "mcpServers": {
    "my-server": { ... }
  }
}

Settings

| Property | Type | Default | Description | |----------|------|---------|-------------| | portBase | number | 19100 | Starting port for managed servers. Ports are allocated sequentially. | | claude | object | omitted (no sync) | Claude Code sync settings: disabled and configPath (default ~/.mcp.json). | | codex | object | omitted (no sync) | Codex sync settings: disabled and configPath (default ~/.codex/config.toml). Direct SSE remotes are skipped; use proxy: true to bridge them. | | dsh | object | omitted (no sync) | DSH sync settings: disabled, home (default ~/.dsh), and profiles (default ["web"]). An empty profile list selects no targets. | | logLevel | string | "info" | Default log level for gateway processes. Options: "debug", "info", "none" |

Configuration Sync

Claude Code, Codex, and enabled DSH profiles use the same sync lifecycle. Target adapters handle file formats and client capabilities; the shared engine handles endpoint mapping, ownership, reconciliation, and file writes.

Each vendor object is optional. An omitted object or disabled: true excludes that vendor from both up and down: its client files, profile dependencies, and ownership records are not inspected or changed. A present object defaults to disabled: false, so "codex": {} syncs Codex at its default path. No vendor objects are added implicitly. If no vendor is enabled, server management still runs but config sync is skipped. disabled must be a boolean; null and boolean values in place of vendor objects are invalid.

The starter template explicitly disables all vendors. This does not change the default for user-supplied objects: omitting disabled enables that vendor.

• up adds or updates generated entries and removes previously owned entries that are now disabled, deleted, or unsupported by that target.
• down my-server removes that entry only if mcp-compose owns it. down removes all owned entries, including servers already removed from the source config.
• Ownership comes only from ~/.mcp-compose/sync-state.json. A matching name in the source config, including a disabled name, does not establish ownership. An untracked same-name entry blocks up rather than being overwritten or adopted, even if its settings match. Rename or deliberately remove the conflicting entry before retrying.
• Other settings and unowned entries are preserved. Recorded entries remain managed even if edited by hand. Keep the ownership file with the generated configuration; disabling/removing a vendor, changing a target path, or deselecting a DSH profile leaves the previous target untouched. Run down while that target is still enabled if cleanup is needed.

All target changes are parsed, validated, and rendered before the first config file is written, for both up and down. Invalid config or ownership files stop sync without overwriting them. Each changed file is replaced atomically, following existing symlinks and retaining permissions; new files use mode 0600. Unchanged settings and ownership records are not rewritten. JSON and TOML are reserialized when entries change; DSH preserves the source text outside its managed block.

Sync checks config and ownership snapshots before saving. If an ownership write fails, it attempts to restore that target's config without overwriting an intervening edit. Previously completed targets remain synced and can be safely revisited on retry. Atomicity applies to individual files, not a transaction across config files and the ownership record; an abrupt process or machine failure between writes may require recovery.

Migrating older settings

Older keys produce an error with the replacement path; they are not silently ignored or converted. Move their values into the vendor objects:

| Old setting | New setting | | --- | --- | | settings.claudeConfigPath | settings.claude.configPath | | settings.codexConfigPath | settings.codex.configPath | | settings.deepseekHarness | settings.dsh |

If you relied on implicit Claude/Codex sync, explicitly add "claude": {} and/or "codex": {}. Existing client files and ownership records need no conversion when the paths remain unchanged. Legacy syncToClaudeConfig / syncToCodexConfig and removal functions require the corresponding vendor object; a disabled object returns an empty result without touching files.

DeepSeek Harness

Install the official @deepseek-ai/dsh-mcp-client in each DSH profile you want to sync. Use the version matching your DSH runtime; the MCP client's npm latest tag may point to an older release. For example, with DSH 0.1.2-rc.1 and an existing web profile:

dsh plugin --profile web add @deepseek-ai/[email protected]

Then add this setting to your mcp-compose.json:

{
  "settings": {
    "dsh": {
      "home": "~/.dsh",
      "profiles": ["web"]
    }
  }
}

mcp-compose up writes MCP entries into ~/.dsh/profiles/web/cordis.patch.yml. Add "headless" to profiles to sync that profile as well, after installing the MCP client there. For a custom DSH home, set home to the same directory used by DSH. Profiles are never discovered or created automatically.

| Source server | DSH connection | | --- | --- | | Local stdio or remote with proxy: true | Streamable HTTP at the gateway's actual localhost port; mcp-compose retains process and OAuth management | | Direct HTTP remote | Streamable HTTP at the remote URL, including configured headers | | Direct SSE remote | Skipped with a warning; use proxy: true to bridge it |

DSH names must match [A-Za-z0-9_-]{1,32}. Names outside that limit are skipped only for DSH. A generated entry looks like this:

# >>> mcp-compose:deepseek-harness
- insert:
    - id: "mcp-compose-my-server"
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: "my-server"
        transport: "streamable-http"
        url: "http://localhost:19100/mcp"
# <<< mcp-compose:deepseek-harness

Only the marked block is replaced. Other patch entries, comments, and !!js expressions keep their original text; sync never evaluates those expressions. An empty [] is replaced when adding the first block, and restored when removing the last entry from an otherwise empty patch. Non-empty flow-style arrays must be converted to block style before enabling sync. Direct HTTP headers are written as literal values, as with the other sync targets; managed proxy credentials stay in mcp-compose.

up checks configured profiles, patch syntax, ownership records, static name/id collisions in the profile patch, and MCP client resolution before starting any servers. It does not install packages, launch DSH, import plugins, or test connections.

DSH cleanup works even if the MCP client package is no longer installed. Untracked entries inside a managed block are rejected instead of silently adopted or deleted.

The entries expose MCP tools to the DSH main harness through its official tool registry. Native Codex and Claude Code modes continue to use their respective synced configuration. To verify activation, load the selected DSH profile and check for mcp__<serverName>__<tool> tools. A successful file sync does not establish runtime loading, authentication, or tool-call success.

Server Types

stdio - Local Command Server

Runs a local command and exposes it as an HTTP endpoint via the built-in gateway.

{
  "my-server": {
    "type": "stdio",
    "command": "uvx",
    "args": ["package@latest"],
    "env": {
      "API_KEY": "xxx"
    },
    "logLevel": "info",
    "resourceLimits": {
      "maxMemory": "512M",
      "maxRestarts": 10,
      "restartDelay": 1000
    }
  }
}

| Property | Type | Required | Description | |----------|------|----------|-------------| | type | "stdio" | No | Auto-detected if command is present | | command | string | Yes | The command to execute | | args | string[] | No | Command arguments | | env | object | No | Environment variables | | disabled | boolean | No | Skip this server when starting | | logLevel | string | No | Override log level: "debug", "info", "none" | | resourceLimits | object | No | Process resource limits (see below) |

sse/http - Remote Server

Passthrough to remote MCP servers. No local process is started by default.

{
  "remote-server": {
    "type": "sse",
    "url": "https://example.com/sse"
  }
}

| Property | Type | Required | Description | |----------|------|----------|-------------| | type | "sse" or "http" | Yes | Server type | | url | string | Yes | Remote server URL | | disabled | boolean | No | Skip this server | | proxy | boolean | No | Enable local proxy with OAuth support (see below) | | headers | object | No | Custom headers to send to the remote server | | logLevel | string | No | Override log level (proxy mode only) | | resourceLimits | object | No | Process resource limits (proxy mode only) |

Without proxy, Claude Code and Codex receive a mcp-compose headers <server> command as headersHelper / http_headers_helper and run it on every connection, so their configs hold the command instead of the credential. Each client runs it with its own environment, and Codex trims that to HOME, PATH, and a few other base variables, so a ${VAR} header value must be exported for the client itself. DSH has no equivalent and writes the values into its profile patch. Use "proxy": true to keep a secret inside the gateway process instead.

Remote Server with OAuth Proxy

Remote servers with "proxy": true are proxied through a local gateway process that handles the full OAuth 2.0 lifecycle automatically. This solves the common issue where OAuth tokens expire and break MCP connections between sessions.

{
  "notion": {
    "type": "http",
    "url": "https://mcp.notion.so/mcp",
    "proxy": true
  }
}

When proxy is enabled:

• A local gateway process is started (managed by pm2, just like stdio servers)
• The gateway handles OAuth 2.0 (PKCE, browser-based consent, automatic token refresh)
• Tokens are cached at ~/.mcp-auth/mcp-compose/ and refreshed automatically when they expire
• The first connection opens a browser for OAuth consent; subsequent connections reuse cached tokens

You can also pass custom headers for API key authentication:

{
  "my-api": {
    "type": "http",
    "url": "https://mcp.example.com/mcp",
    "proxy": true,
    "headers": {
      "Authorization": "Bearer ${API_KEY}"
    }
  }
}

Resource Limits

Control pm2 process management behavior for managed servers.

{
  "resourceLimits": {
    "maxMemory": "512M",
    "maxRestarts": 10,
    "restartDelay": 1000
  }
}

| Property | Type | Default | Description | |----------|------|---------|-------------| | maxMemory | string or number | - | Memory limit before restart. String: "512M", "1G". Number: bytes. | | maxRestarts | number | 10 | Maximum restart attempts before giving up | | restartDelay | number | 1000 | Delay between restarts in milliseconds |

Disabling Servers

Add "disabled": true to skip a server without removing its config:

{
  "my-server": {
    "command": "uvx",
    "args": ["some-package"],
    "disabled": true
  }
}

Example Configuration

{
  "settings": {
    "portBase": 19100,
    "claude": {},
    "codex": {},
    "logLevel": "info"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/home/user/documents"],
      "resourceLimits": {
        "maxMemory": "256M"
      }
    },
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    },
    "aws-docs": {
      "type": "http",
      "url": "https://mcp.aws.example.com/mcp"
    },
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.so/mcp",
      "proxy": true
    },
    "experimental": {
      "command": "node",
      "args": ["./my-experimental-server.js"],
      "disabled": true
    }
  }
}

Tip: 1Password CLI Secrets

Use 1Password secret references when MCP servers need API keys or tokens. This lets you unlock 1Password once, start all long-running MCP servers with resolved credentials, and then run each agent session without handing credentials to the agent itself.

mcp-compose expands environment variables in its JSON config before starting servers, so keep the 1Password paths in a local env file:

# mcp-compose.env
GITHUB_PERSONAL_ACCESS_TOKEN=op://Private/github-mcp/token
FIRECRAWL_API_KEY=op://Private/firecrawl/api-key

Then reference those variables from mcp-compose.json:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}"
      }
    }
  }
}

Start or restart the servers through op run:

op signin
op run --env-file ./mcp-compose.env -- mcp-compose up

op signin only prompts when the CLI is not already authenticated. If multiple 1Password accounts are configured, choose one with op --account <account> run ... or set OP_ACCOUNT. op run resolves environment variables whose values are op://vault/item/field secret references before mcp-compose starts the managed servers. This keeps plaintext secrets out of the tracked config and agent config, but the managed MCP server process still receives the resolved environment variables. Secret output is masked by default.

op inject can also resolve {{ op://vault/item/field }} placeholders into a temporary config file, but this is not recommended because the output file contains plaintext secrets:

op inject -i mcp-compose.1password.json -o /tmp/mcp-compose.json
mcp-compose -c /tmp/mcp-compose.json up
rm /tmp/mcp-compose.json

Prefer the op run --env-file flow so the tracked config contains only environment variable names and the env file contains only 1Password references.

CLI Reference

mcp-compose up [servers...]      Start or update servers (only restarts changed configs)
mcp-compose down [servers...]    Stop servers
mcp-compose restart [servers...] Restart servers
mcp-compose status               Show configured servers and their processes
mcp-compose logs [server] [-f]   View logs (follow with -f)
mcp-compose headers <server>     Print a remote server's headers as JSON (run by client header helpers)

Options

| Option | Description | |--------|-------------| | -c, --config <path> | Specify config file path | | -V, --version | Show version | | -h, --help | Show help |

Examples

# Start all servers
mcp-compose up

# Start specific servers
mcp-compose up github filesystem

# Stop specific servers
mcp-compose down github

# Stop all servers
mcp-compose down

# Use custom config file
mcp-compose -c ./custom-config.json up

# View logs for specific server
mcp-compose logs github

# Follow all logs
mcp-compose logs -f

How It Works

1. stdio servers: Wrapped by a built-in gateway that bridges stdio to MCP Streamable HTTP, managed by pm2
2. Remote servers: Registered directly in Claude Code config (no local process), with headers fetched from mcp-compose headers <server> at connection time
3. Remote servers with proxy: Proxied through a local gateway with built-in OAuth 2.0 lifecycle management (PKCE, token refresh)
4. Config sync: Auto-updates ~/.mcp.json for Claude Code, ~/.codex/config.toml for Codex CLI, and explicitly enabled DeepSeek Harness profile patches
5. Port allocation: Automatically detects port conflicts and uses next available port

Each managed server gets an internal port starting from portBase (default 19100). If a port is in use, the next available port is automatically selected.

Gateway compatibility

The gateway supports the stateless MCP 2026-07-28 transport and the earlier session-based transport. It detects the client and backend eras independently, so a modern client can use a legacy backend and a legacy client can use a modern backend.

For a modern request, _meta.io.modelcontextprotocol/protocolVersion and _meta.io.modelcontextprotocol/clientCapabilities are required and must agree with MCP-Protocol-Version. Mcp-Method must match the JSON-RPC method. Mcp-Name is required only for tools/call, prompts/get, and resources/read, where it must match the named tool, prompt, or resource. Mismatched, missing, malformed, unsupported, or extra routing headers are rejected before forwarding.

Modern-to-modern proxy traffic is relayed without legacy compatibility handling, including the client request ID and request-scoped SSE events. The gateway synthesizes only the explicit era bridge: initialize and server/discover, session metadata, completion markers, resource-not-found error codes, and legacy-only methods. When a legacy client uses a modern backend, its clientInfo and capabilities become the modern per-request metadata. A legacy backend is initialized once by the gateway, rather than once per downstream client session.

subscriptions/listen uses the standard notifications filter object and a separate SSE stream. A locally synthesized legacy subscription first emits notifications/subscriptions/acknowledged, then matches backend notification methods against the requested standard or extension filters; every frame carries _meta.io.modelcontextprotocol/subscriptionId equal to the listen request's JSON-RPC ID. Internal ownership keeps identical request IDs from different clients isolated. Modern backends retain their own subscription stream unchanged for both client eras. Request-scoped events never leak into a subscription, and legacy change notifications never leak into an unrelated request. Idle locally synthesized streams send keep-alive comments.

For proxy servers, configured headers, supported protocol metadata, and Mcp-Param-* extension headers are forwarded upstream; arbitrary client headers are not. The gateway preserves an upstream status and only the safe response headers (Content-Type, Cache-Control, WWW-Authenticate, and MCP-Protocol-Version) for same-era proxy responses. Cross-era responses use gateway-generated transport metadata.

The local endpoint accepts requests without an Origin header for native MCP clients. Browser requests must use a literal loopback origin (localhost, 127.0.0.1, or [::1]); other origins are rejected and not reflected in CORS headers.

Managed OAuth follows the MCP authorization specification: it requires advertised PKCE S256 support, verifies that protected-resource metadata binds to the exact requested resource, validates the exact authorization-server issuer and callback issuer, and cancels discovery, token work, and the callback listener when the client request ends. A Bearer challenge scope is authoritative; when it is absent on an initial authorization, protected-resource scopes_supported supplies the scope. A 401 challenge or 403 insufficient_scope response can start authorization. Step-up requests the union of the existing grant and newly challenged scopes, while an unscoped retry retains the existing grant and refresh never expands it. Only Bearer token responses are forwarded to the MCP server.

In passthrough mode, a shared legacy upstream session, including the deprecated HTTP+SSE ("type": "sse") transport, is bound to the credential that created it. A request with another credential is rejected until that session closes; its cleanup uses the owning credential. An HTTP+SSE server may advertise a message endpoint only on the configured upstream origin. Modern upstream requests remain independently credentialed.

The gateway does not translate legacy server-initiated sampling, elicitation, or roots requests into multi-round-trip requests (MRTR). Those requests are dropped rather than being delivered on another request or subscription stream.

Features

• Zero external dependencies for transport: Built-in MCP gateway replaces supergateway and mcp-remote
• Built-in OAuth 2.0: PKCE authorization, token refresh, and persistent token storage for remote servers
• Incremental updates: Only restarts servers with changed configurations
• Automatic port conflict detection: Skips ports in use and allocates next available
• Config validation: Validates configuration structure with helpful error messages
• Resource limits: Control memory usage and restart behavior per server
• Process management: Auto-restart with configurable limits via pm2
• Non-destructive config sync: Merges with existing Claude Code config, and drops only the entries it wrote itself once a server is disabled or removed
• Credentials in one place: Claude Code and Codex get a header helper command, so remote server secrets stay in the mcp-compose config

Requirements

• Node.js 18+ (includes npx)

License

MIT