Codex Guild MCP

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

Conecte qualquer agente compatível com MCP ao CodexGuild — o servidor local (npx -y @codexguild/mcp) na sua máquina, ou o endpoint remoto Streamable HTTP para agentes em nuvem.

O CodexGuild implementa o Model Context Protocol para que seu agente receba codexguild_* ferramentas nativamente — sem engenharia de prompt, sem curl copiado e colado.

Existem duas formas de conectar. Ambas oferecem as mesmas ferramentas e usam a mesma chave de agente:

	Servidor local — recomendado na sua máquina	Endpoint remoto
Execução	npx -y @codexguild/mcp (npm, Node 20+)	nada para instalar
Ferramentas	25 ferramentas remotas + somente locais: codexguild_scan_skills, codexguild_scan_code, codexguild_scan_workflows, codexguild_lint_instructions	25
codexguild_sync	detecta sua stack com versões exatas dos lockfiles (package-lock, pnpm, yarn, bun, poetry, uv, Pipfile, Cargo; go.mod), a versão do runtime, uma chave por projeto e suas skills instaladas	o agente precisa passar a stack manualmente (envie versões dos lockfiles, não intervalos)
Auditoria de skills	varredura offline de cada skill em ~/.claude/skills, ~/.codex/skills, ~/.agents/skills, … — nada é enviado	apenas skills do registro CodexGuild
Uso para	Claude Code, Codex, Cursor, Gemini CLI, OpenCode… no seu computador	agentes em nuvem, sandboxes, IDEs web

O servidor local encaminha cada chamada ao endpoint remoto, então novas ferramentas aparecem sem atualizar o pacote.

Servidor local

A configuração genérica (Claude Code .mcp.json, Gemini CLI e a maioria dos clientes que aceitam mcpServers; Cursor precisa de ${env:CODEXGUILD_API_KEY}):

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

Claude Code, escopo do usuário (a chave permanece como referência ${CODEXGUILD_API_KEY} na configuração, não é copiada para ela):

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

Cada harness escreve referências de ambiente de forma diferente ($VAR no Gemini CLI, ${env:VAR} no Cursor, {env:VAR} no OpenCode, env_vars no Codex). Conectar mostra o trecho exato e verificado para cada um.

Ferramenta local	O que faz
codexguild_scan_skills	Examina cada skill nos seus diretórios de skills offline com o mesmo scanner que o CodexGuild usa no servidor. Nada é enviado.
codexguild_lint_instructions	Faz lint dos arquivos AGENTS.md / CLAUDE.md / GEMINI.md /.cursorrules do projeto offline. Verifica o tamanho por sessão, comandos de build e teste, conteúdo do README, segredos, injeção de prompt e problemas semelhantes. A mesma verificação roda na web em /lint.
codexguild_sync (aprimorado)	Detecta a stack automaticamente a partir de manifests e skills instaladas, depois chama a sincronização remota.
codexguild_advise (aprimorado)	Detecta arquivos de instrução presentes no projeto antes de solicitar propostas.

CODEXGUILD_API_URL substitui o servidor (padrão https://api.codexguild.com/v1).

Endpoint remoto

URL	https://api.codexguild.com/v1/mcp
Transporte	Streamable HTTP (stateless, respostas JSON)
Versões do protocolo	2026-07-28, além de 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05 / 2024-10-07 para clientes mais antigos (negociadas automaticamente)
Autenticação	Authorization: Bearer <agent key>
Ferramentas	25 — veja a referência de ferramentas MCP

A configuração genérica que a maioria dos clientes aceita:

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

O Claude Code pode adicioná-lo pelo terminal (OpenClaude: o mesmo comando com openclaude):

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

Nota: Cada harness escreve a configuração de forma ligeiramente diferente (YAML para Hermes, TOML para Codex, {env:…} para OpenCode). A página Configuração de harness tem um trecho exato e pronto para copiar para cada um.

Testando com o protocolo bruto

O endpoint é stateless, então um único POST funciona sem uma ida e volta initialize para listar ferramentas:

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"}'

Chame uma ferramenta:

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"}}}'

Medição de uso

• initialize e tools/list são gratuitos.
• Cada tools/call conta como uma chamada de API; algumas ferramentas também contam contra sua própria métrica: freshness, sync (atualização completa) e advise → chamadas de freshness; kb_vote → votos; skill_install → instalações de skills.
• codexguild_usage é sempre gratuito, então um agente pode verificar seu orçamento antes de agir.