MCP usage

O Simplafy Admin expõe um servidor MCP (Model Context Protocol) para coding agents via Streamable HTTP. O endpoint unificado fica em https://mcp-admin.simplafy.com.br/mcp e agrega famílias de tools (PM Board, BI, Knowledge Base, Lab, Langfuse) além de backends proxiados dinamicamente.

Endpoint /mcp

O servidor expõe um endpoint unificado /mcp e endpoints especializados por família de tools. Endpoints especializados reduzem a quantidade de definições de tool carregadas pelo cliente, economizando tokens no contexto do agent.

Todas as rotas exigem POST. O transporte é Streamable HTTP stateless (sem sessionId), portanto cada request abre e fecha sua própria conexão de transport.

Accept headers obrigatórios

O Streamable HTTP transport exige que o cliente declare aceitar tanto JSON quanto SSE no mesmo request. Sem isso o transport rejeita a requisição.

POST /mcp HTTP/1.1
Host: mcp-admin.simplafy.com.br
Authorization: Bearer <SEU_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream

Cabeçalhos obrigatórios:

• Authorization: Bearer <token> — token OAuth ou API token do agent.
• Content-Type: application/json — payload sempre JSON-RPC 2.0.
• Accept: application/json, text/event-stream — exigência do SDK MCP para Streamable HTTP.

JSON-RPC requests

Todas as chamadas seguem JSON-RPC 2.0. Os métodos principais do protocolo MCP são initialize, tools/list e tools/call.

curl -sS https://mcp-admin.simplafy.com.br/mcp \
  -H "Authorization: Bearer $SIMPLAFY_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

curl -sS https://mcp-admin.simplafy.com.br/mcp \
  -H "Authorization: Bearer $SIMPLAFY_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

curl -sS https://mcp-admin.simplafy.com.br/mcp/pm \
  -H "Authorization: Bearer $SIMPLAFY_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "pm_list_stories",
      "arguments": { "status": "in_progress" }
    }
  }'

Códigos de erro retornados pelo servidor:

• BACKEND_NOT_FOUND (404) — slug de proxy inexistente ou inativo.
• FORBIDDEN_SCOPE (403) — agent sem o scope proxy:<slug>:* necessário para o backend.
• BACKEND_UNAVAILABLE — tool de proxy chamada mas o backend está desconectado.
• PROXY_ERROR — backend conectado retornou erro ao executar a tool.
• PAYLOAD_TOO_LARGE (413) — body excede MCP_BODY_LIMIT.

Conectar em Claude Code

Adicione o servidor ao seu arquivo .mcp.json (workspace) ou ao MCP config global.

{
  "mcpServers": {
    "simplafy-admin": {
      "type": "http",
      "url": "https://mcp-admin.simplafy.com.br/mcp",
      "headers": {
        "Authorization": "Bearer ${SIMPLAFY_ADMIN_TOKEN}"
      }
    }
  }
}

Para reduzir o número de tools carregadas no contexto, aponte para um endpoint especializado:

{
  "mcpServers": {
    "simplafy-admin-pm": {
      "type": "http",
      "url": "https://mcp-admin.simplafy.com.br/mcp/pm",
      "headers": {
        "Authorization": "Bearer ${SIMPLAFY_ADMIN_TOKEN}"
      }
    },
    "simplafy-admin-bi": {
      "type": "http",
      "url": "https://mcp-admin.simplafy.com.br/mcp/bi",
      "headers": {
        "Authorization": "Bearer ${SIMPLAFY_ADMIN_TOKEN}"
      }
    }
  }
}

Exporte SIMPLAFY_ADMIN_TOKEN no shell antes de iniciar o Claude Code, ou substitua pelo valor literal.

Conectar em Cursor

No Cursor, edite ~/.cursor/mcp.json (ou o equivalente do workspace) com a mesma estrutura HTTP:

{
  "mcpServers": {
    "simplafy-admin": {
      "url": "https://mcp-admin.simplafy.com.br/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_AQUI"
      }
    }
  }
}

Reinicie o Cursor após editar o arquivo para que o cliente reconecte ao servidor.

Conectar em Codex

O OpenAI Codex CLI suporta MCP via configuração TOML. Adicione um bloco para o servidor Admin em ~/.codex/config.toml:

[mcp_servers.simplafy-admin]
url = "https://mcp-admin.simplafy.com.br/mcp"

[mcp_servers.simplafy-admin.headers]
Authorization = "Bearer SEU_TOKEN_AQUI"

Para uso pontual em um único projeto, prefira um endpoint especializado para limitar o tool list:

[mcp_servers.simplafy-admin-kb]
url = "https://mcp-admin.simplafy.com.br/mcp/kb"

[mcp_servers.simplafy-admin-kb.headers]
Authorization = "Bearer SEU_TOKEN_AQUI"