# Create MCP > Add a new MCP server to all AI tool configs. Use when user says "add MCP server", "new MCP server", "create MCP", "add tool to MCP", or wants to register a new MCP server across Claude Code, Codex, Cursor, and OpenCode. Use when this capability is needed. - Skill: `tomevault-io/create-mcp` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/create-mcp` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/create-mcp/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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..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..tools.]` 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](https://github.com/ralphkrauss/agent-orchestrator) — distributed by [TomeVault](https://tomevault.io).