Create MCP

Add MCP Server

Add a new MCP server to all AI tool config files, keeping the cross-tool inventory in sync.

If the project documents its own MCP architecture and credential conventions, read that documentation first.

Instructions

Step 1: Gather Server Details

Determine the following from the user's request or by asking (one round max):

1. Name -- kebab-case server identifier (e.g., my-tool-local, my-tool-stg)
2. Tier -- 1 (third-party image), 2 (custom CLI wrapper, if the project ships one), or custom (Node.js/uv script)
3. Environment -- Local or Staging (staging names should include a tenant or environment identifier)
4. Transport -- stdio (Docker/Node/uv command) or HTTP (url + headers)
5. Access mode -- read-only or read-write
6. Docker image or command -- what runs the server
7. Environment variables -- which env vars are needed, which are secrets
8. Guardrails (Tier 2 only) -- allowed patterns, blocked patterns, strip args, prepend args

Step 2: Add to .mcp.json (Claude Code -- the reference config)

This is the authoritative definition. All other configs are ports of this.

Add the server entry under mcpServers. Include a _comment field describing tier, environment, access mode, and prerequisites.

Key conventions:

• Use ${VAR:-default} for env var substitution with defaults
• Use ${VAR:-} (empty default) for credential-driven activation
• Docker servers use "type": "stdio", "command": "docker", "args": ["run", "-i", "--rm", ...]
• Pass env vars to Docker with -e VAR_NAME in args + matching env block
• Shared repo configs should use node scripts/run-npx-mcp.mjs ... instead of raw npx ... for stdio servers launched via npm shims
• HTTP servers use "type": "stdio" with node scripts/run-npx-mcp.mjs -y mcp-remote ... proxy (not direct HTTP)

See references/config-formats.md for the exact template.

Step 3: Add to .codex/config.toml (Codex)

Translate the Claude config to TOML format:

• command and args are TOML key/value pairs
• env becomes [mcp_servers.<name>.env] table
• JSON arrays in env values need careful TOML string escaping
• HTTP servers use url + http_headers (no npx mcp-remote wrapper)
• Secret-bearing stdio servers should use scripts/mcp-secret-bridge.mjs so repo config can map canonical user-level secret names into the child env names expected by the server
• If the child command would be raw npx, invoke node scripts/run-npx-mcp.mjs ... instead so native Windows works from the shared config
• Add [mcp_servers.<name>.tools.<tool>] sections with approval_mode = "approve" if tools need gating

Only keep static non-secret values in repo env tables. The bridge handles secret remapping and any user-level secrets file the project uses as fallback.

See references/config-formats.md for the exact template.

Step 4: Add to .cursor/mcp.json (Cursor)

Translate the Claude config to Cursor format:

• Same JSON structure as Claude but no type field, no _comment
• Secret-bearing stdio servers should use scripts/mcp-secret-bridge.mjs
• If the child command would be raw npx, invoke node scripts/run-npx-mcp.mjs ... instead
• Only keep static non-secret values in the Cursor env block
• Do not reintroduce repo-local .cursor/mcp.env

See references/config-formats.md for the exact template.

Step 5: Add to opencode.json (OpenCode)

Translate the Claude config to OpenCode format:

• command is a single array: ["docker", "run", "-i", "--rm", ...] (command + args combined)
• environment replaces env
• type: "local" for stdio, type: "remote" for HTTP
• HTTP servers use url + headers directly (no proxy)
• Secret-bearing stdio servers should use scripts/mcp-secret-bridge.mjs
• If the child command would be raw npx, invoke node scripts/run-npx-mcp.mjs ... instead
• Only keep static non-secret values in the OpenCode environment block

See references/config-formats.md for the exact template.

Step 6: Update Documentation

If the project maintains an MCP inventory doc, update it:

1. Server Inventory table -- add a row with server name, tier, environment, access mode, prerequisites, and description
2. Cross-Tool Server Mapping table -- add a row showing which tools have the server (use checkmark or --)
3. Environment Variables Reference table -- add rows for any new env vars with description and which server uses them

Step 7: Update Credential Examples

If the server requires credentials:

1. Document required env vars per tool config in whatever the project's MCP docs are
2. Canonical bootstrap template -- if the project uses a shared secret-bootstrap script, add the canonical variable there
3. OpenCode / Cursor / Codex bridge -- ensure the canonical variable is covered by the bridge profile and any config examples when relevant

Step 8: Verify

• Confirm server name follows the project's naming conventions (e.g., includes a tenant/environment identifier for staging)
• Confirm all 4 config files are syntactically valid (no trailing commas in JSON, valid TOML)
• Confirm the server entry is consistent across all configs (same Docker args, same env vars)
• For Tier 2 servers, confirm guardrail mode is correct (open, allowlist-only, or blocklist-only -- never both)

Critical Rules

• .mcp.json is the reference config -- define the server there first, then port to other formats
• Never use both allowed and blocked patterns on the same Tier 2 server -- pick one mode
• Staging servers include a tenant/environment ID in the name (e.g., stg-tenant-region, not bare staging)
• Canonical secret names live outside the repo -- preserve user-level canonical names rather than rewriting them per server
• Cursor secret-bearing stdio servers should use the bridge -- do not add .cursor/mcp.env back or rely on launch-env-only secret wiring
• OpenCode secret-bearing stdio servers should use the bridge -- do not add .opencode/secrets/* requirements back or rely on launch-env-only secret wiring
• Codex secret-bearing stdio servers should use the bridge -- do not reintroduce repo-specific secret tables in ~/.codex/config.toml
• Docker Desktop networking: use host.docker.internal (not localhost) for host ports accessed from Docker containers on macOS/Windows

Checklist

• Server added to .mcp.json with _comment, correct transport, env vars
• Server added to .codex/config.toml with TOML-translated config
• Server added to .cursor/mcp.json (or documented why skipped)
• Server added to opencode.json with OpenCode-format translation
• Project's secret-bootstrap script updated (if a new canonical secret is needed)
• Project's MCP inventory doc updated (if maintained)
• Cross-Tool Server Mapping updated
• Environment Variables Reference updated (if new vars)
• Credential examples updated in all tool sections

Reference

• references/config-formats.md -- per-tool config templates
• .mcp.json -- Claude Code reference config (authoritative)
• .codex/config.toml -- Codex config
• .cursor/mcp.json -- Cursor config
• opencode.json -- OpenCode config

Source: ralphkrauss/agent-orchestrator — distributed by TomeVault.