Mracos Mcp

mcp

Manage MCP servers from a single config file (~/.mcp-servers.json) and sync to multiple AI coding clients.

Supported targets:

• Claude Code - ~/.claude.json (mcpServers)
• Codex - ~/.codex/config.toml ([mcp_servers.*])

Install

zinit

# as command (in a `zinit for as"command"` block)
pick"bin/*" mracos/mcp

# or standalone
zinit ice as"command" pick"bin/*"
zinit light mracos/mcp

Clone + PATH

git clone https://github.com/mracos/mcp ~/.mcp
export PATH="$HOME/.mcp/bin:$PATH"

Requirements

• bash 3.2+ (macOS stock bash works)
• jq - JSON processing (all commands)
• Node.js / npx - daemon management (mcp daemon, stdio-http-proxy servers)
• mcp-proxy - stdio-to-HTTP proxy (npx mcp-proxy)
• envsubst (gettext) - env var expansion in daemon configs
• launcher - only if you set MCP_BACKEND=launchd

Usage

mcp list                          # List all configured servers
mcp add notion https://...        # Add HTTP server
mcp add tool -- npx -y @pkg/mcp   # Add stdio server
mcp remove                  # Remove a server
mcp edit                          # Open in $EDITOR
mcp apply                         # Sync into clients
mcp show                    # Show server config
mcp daemon [start|stop|status]    # Manage proxy daemons
mcp logs [name]                   # Tail daemon logs

Server Types

HTTP

Direct connection to a remote MCP server:

mcp add notion https://mcp.notion.com/mcp

stdio

Spawns a new process per session:

mcp add mytool -- npx -y @example/mcp

stdio-http-proxy

stdio servers spawn a new process for every Claude Code session - slow startup, no shared state, duplicate processes if you have multiple windows. stdio-http-proxy runs the server once as a persistent daemon via mcp-proxy and connects clients over HTTP:

{
  "myserver": {
    "type": "stdio-http-proxy",
    "command": "npx",
    "args": ["-y", "@example/mcp"],
    "env": { "API_KEY": "${MY_API_KEY}" },
    "port": 8081
  }

Use unique ports per server. mcp apply starts daemons automatically and writes SSE endpoints to Claude Code config.

Why SSE instead of HTTP?

Claude Code assumes http endpoints support OAuth and tries discovery. Local mcp-proxy doesn't implement OAuth, causing 404 errors. sse transport skips OAuth discovery and connects directly.

For Codex, proxied servers are written as streamable HTTP URLs (http://localhost:/mcp).

Env Vars

Add env vars with --env on mcp add:

mcp add --env API_KEY=sk-123 mytool -- npx -y @example/mcp

Or edit directly with mcp edit:

{
  "myserver": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@example/mcp"],
    "env": { "API_KEY": "${MY_API_KEY}" }
  }
}

${VAR} references in env values are expanded via envsubst when generating daemon configs.

How It Works

~/.mcp-servers.json is the source of truth. mcp apply reads it and:

1. Starts daemons for stdio-http-proxy servers (via the active backend)
2. Merges server configs into ~/.claude.json
3. Syncs server configs into ~/.codex/config.toml

Existing non-MCP keys in both target files are preserved.

Daemon backends

mcp daemon dispatches to a pluggable backend selected by MCP_BACKEND:

| Backend | When to use | Notes | |---|---|---| | pm2 (default) | Cross-platform, fast iteration | Requires npx; pm2 installed lazily on first use | | launchd | macOS native, survives reboots | Requires the launcher CLI in PATH |

export MCP_BACKEND=launchd   # or pm2 (default)
mcp daemon start

Both backends are self-contained: top-level binaries (npx, the inner command) are resolved to absolute paths at generation time and PATH is injected into the daemon's environment so child spawns work even when the launchd/pm2 process starts from a minimal env.

The backend interface is defined in lib/lib-backend.bash; see [docs/adrs/0001-mcp-backend-abstraction.md](docs/adrs/0001-mcp-backend-abstraction.md) for the design.

Testing

npm install
npm test

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mracos
• Source: mracos/mcp
• License: MIT

Install and usage instructions live in the source repository linked above.