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) 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 (npm, Node 20+)	nothing to install
Tools	25 remote tools + local-only codexguild_scan_skills, codexguild_scan_code, codexguild_scan_workflows, codexguild_lint_instructions	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 call to the remote endpoint, so new tools show up without updating the package.

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"],
      "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"],"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_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_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"

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.