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.
No installation required - use npx. (RECOMMENDED)
npx -y mcp-compose statusYou can add an alias to ~/.bashrc or ~/.zshrc:
alias mcp-compose='npx -y mcp-compose'Or install globally:
npm install -g mcp-composemcp-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 serversmcp-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.
{
"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": { ... }
}
}| 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" |
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.
upadds or updates generated entries and removes previously owned entries that are now disabled, deleted, or unsupported by that target.down my-serverremoves that entry only if mcp-compose owns it.downremoves 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 blocksuprather 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
downwhile 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.
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.
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/dsh-mcp-client@0.1.2-rc.1Then 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-harnessOnly 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.
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) |
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 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}"
}
}
}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 |
Add "disabled": true to skip a server without removing its config:
{
"my-server": {
"command": "uvx",
"args": ["some-package"],
"disabled": true
}
}{
"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
}
}
}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-keyThen 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 upop 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.jsonPrefer the op run --env-file flow so the tracked config contains only environment variable names and the env file contains only 1Password references.
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)
| Option | Description |
|---|---|
-c, --config <path> |
Specify config file path |
-V, --version |
Show version |
-h, --help |
Show help |
# 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- stdio servers: Wrapped by a built-in gateway that bridges stdio to MCP Streamable HTTP, managed by pm2
- Remote servers: Registered directly in Claude Code config (no local process), with headers fetched from
mcp-compose headers <server>at connection time - Remote servers with proxy: Proxied through a local gateway with built-in OAuth 2.0 lifecycle management (PKCE, token refresh)
- Config sync: Auto-updates
~/.mcp.jsonfor Claude Code,~/.codex/config.tomlfor Codex CLI, and explicitly enabled DeepSeek Harness profile patches - 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.
The gateway speaks the stateless MCP 2026-07-28 transport and the earlier session-based one. It detects the client era and the backend era independently, so either side can be either era.
| Area | Behavior |
|---|---|
| Era bridging | Same-era traffic is relayed untouched, request IDs and request-scoped SSE events included. Only initialize, server/discover, session metadata, completion markers, resource-not-found codes, and legacy-only methods are translated. The gateway initializes a legacy backend once, not once per client session. |
| Request validation | A modern request must carry MCP-Protocol-Version, matching _meta protocol version and client capabilities, Mcp-Method matching the JSON-RPC method, and Mcp-Name for tools/call, prompts/get, and resources/read. Mismatched, malformed, or extra routing headers are rejected before forwarding. |
| Notifications | subscriptions/listen gets its own SSE stream. Request-scoped events and subscription notifications never cross into each other, and identical request IDs from different clients stay isolated. |
| Proxy headers | Configured headers, supported protocol metadata, and Mcp-Param-* go upstream; arbitrary client headers do not. A same-era response keeps the upstream status and only Content-Type, Cache-Control, WWW-Authenticate, and MCP-Protocol-Version. |
| Origin | A native client may omit Origin. A browser must use a literal loopback origin (localhost, 127.0.0.1, [::1]); anything else is rejected and never reflected in CORS headers. |
| OAuth | Managed OAuth follows the authorization spec: PKCE S256, protected-resource metadata bound to the exact resource, validated issuers, scope taken from the Bearer challenge, and refresh that never widens scope. Only Bearer tokens reach the MCP server. |
Two limits are worth knowing before you rely on them:
- In passthrough mode, a shared legacy upstream session belongs to the credential that opened it, including over the deprecated HTTP+SSE (
"type": "sse") transport. A second credential is rejected until that session ends. Modern upstream requests stay independently credentialed. - Legacy server-initiated sampling, elicitation, and roots requests are dropped rather than delivered on an unrelated stream. There is no multi-round-trip (MRTR) bridge.
- 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
- Node.js 18+ (includes npx)
MIT