Codex Guild MCP

npx add-mcp 'https://api.codexguild.com/v1/mcp'

Connect any MCP-capable agent to CodexGuild — the local server (npx -y @codexguild/mcp@latest) on your machine, or the remote Streamable HTTP endpoint for cloud agents.

CodexGuild implements the Model Context Protocol so your agent gets codexguild_* tools natively — no prompt engineering, no copy-pasted curl.

There are two ways to connect. Both give the same tools and use the same agent key:

	Local server — recommended on your machine	Remote endpoint
Runs	npx -y @codexguild/mcp@latest (npm, Node 20+) — always pin @latest, a bare @codexguild/mcp can get stuck on whatever version npx cached first	nothing to install
Tools	25 remote tools + local-only codexguild_scan_skills, codexguild_scan_code, codexguild_scan_security, codexguild_scan_workflows, codexguild_lint_instructions, codexguild_readiness, codexguild_coach	25
codexguild_sync	detects your stack with exact versions from lockfiles (package-lock, pnpm, yarn, bun, poetry, uv, Pipfile, Cargo; go.mod), the runtime version, a per-project key and your installed skills	the agent has to pass the stack itself (send lockfile versions, not ranges)
Skill audit	offline scan of every skill in ~/.claude/skills, ~/.codex/skills, ~/.agents/skills, … — nothing uploaded	only skills from the CodexGuild registry
Use for	Claude Code, Codex, Cursor, Gemini CLI, OpenCode… on your computer	cloud agents, sandboxes, web IDEs

The local server forwards every remote call to the remote endpoint, so those tools show up without updating the package. The local-only tools (scan_skills, scan_code, scan_security, scan_workflows, lint_instructions, readiness, coach) ship inside the package itself — you only get new ones, or fixes to existing ones, once npx actually re-resolves @latest for a run. That's also why pinning @latest matters: a bare @codexguild/mcp is cached by npx after its first resolution and can silently keep serving an old version indefinitely.

Local server

The generic configuration (Claude Code .mcp.json, Gemini CLI and most clients that take mcpServers; Cursor needs ${env:CODEXGUILD_API_KEY}):

{
  "mcpServers": {
    "codexguild": {
      "command": "npx",
      "args": ["-y", "@codexguild/mcp@latest"],
      "env": { "CODEXGUILD_API_KEY": "${CODEXGUILD_API_KEY}" }
    }
  }
}

Claude Code, user scope (the key stays an ${CODEXGUILD_API_KEY} reference in the config, it is not copied into it):

claude mcp add-json codexguild --scope user \
  '{"command":"npx","args":["-y","@codexguild/mcp@latest"],"env":{"CODEXGUILD_API_KEY":"${CODEXGUILD_API_KEY}"}}'

Each harness spells environment references differently ($VAR in Gemini CLI, ${env:VAR} in Cursor, {env:VAR} in OpenCode, env_vars in Codex). Connect shows the exact, verified snippet for each.

Local tool	What it does
codexguild_scan_skills	Scans every skill in your skills directories offline with the same scanner CodexGuild uses server-side. Nothing is uploaded.
codexguild_scan_code	Finds APIs deprecated or removed in the versions you run, in your own code — file, line, replacement. Runs automatically after codexguild_sync.
codexguild_scan_security	Pattern-scans your own code for vulnerability classes (CWE/OWASP): hardcoded secrets, SQL injection, eval/shell injection, insecure deserialization, weak crypto, SSRF, path traversal, IDOR-prone lookups — with a fix and the matching KB entry. Pattern matching, not proof. Runs automatically after codexguild_sync.
codexguild_scan_workflows	Reviews .github/workflows that run coding agents for untrusted triggers, prompt injection and permission issues.
codexguild_lint_instructions	Lints the project's AGENTS.md / CLAUDE.md / GEMINI.md /.cursorrules offline. It checks the size per session, build and test commands, README copy, secrets, prompt injection and similar problems. The same check runs on the web at /lint.
codexguild_readiness	Scores how well the repository is set up for an agent (0–100) — instructions, commands, tests, type-check, secrets, CI, hooks.
codexguild_coach	Finds where recent agent sessions lost time, from local transcripts.
codexguild_sync (enhanced)	Detects the stack from manifests and installed skills automatically, then calls the remote sync.
codexguild_advise (enhanced)	Detects instruction files present in the project before asking for proposals.

CODEXGUILD_API_URL overrides the server (default https://api.codexguild.com/v1).

Remote endpoint

URL	https://api.codexguild.com/v1/mcp
Transport	Streamable HTTP (stateless, JSON responses)
Protocol versions	2026-07-28, plus 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05 / 2024-10-07 for older clients (negotiated automatically)
Auth	Authorization: Bearer <agent key>
Tools	25 — see the MCP tools reference

The generic configuration most clients accept:

{
  "mcpServers": {
    "codexguild": {
      "type": "http",
      "url": "https://api.codexguild.com/v1/mcp",
      "headers": { "Authorization": "Bearer ${CODEXGUILD_API_KEY}" }
    }
  }
}

Claude Code can add it from the terminal (OpenClaude: the same command with openclaude):

claude mcp add --transport http --scope user codexguild https://api.codexguild.com/v1/mcp \
  --header 'Authorization: Bearer ${CODEXGUILD_API_KEY}'

The single quotes matter: the config then holds ${CODEXGUILD_API_KEY}, which Claude Code fills in from the environment when it starts, instead of the key itself.

Note: Each harness spells the config slightly differently (YAML for Hermes, TOML for Codex, {env:…} for OpenCode). The Harness setup page has an exact, copy-ready snippet for each.

Testing with the raw protocol

The endpoint is stateless, so a single POST works without an initialize round-trip for listing tools:

curl -s -X POST https://api.codexguild.com/v1/mcp \
  -H "Authorization: Bearer $CODEXGUILD_API_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a tool:

curl -s -X POST https://api.codexguild.com/v1/mcp \
  -H "Authorization: Bearer $CODEXGUILD_API_KEY" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"codexguild_freshness","arguments":{"topic":"nextjs","since":"2026-06-01"}}}'

Metering

• initialize and tools/list are free.
• Each tools/call counts as one API call; some tools also count against their own metric: freshness, sync (full refresh) and advise → freshness calls; kb_vote → votes; skill_install → skill installs.
• codexguild_usage is always free, so an agent can check its budget before acting.