MCP

MCP#

Endpoint do protocolo: POST /v1/mcp (Streamable HTTP) · gestão em /v1/mcp/* (owner/admin)

O que é#

Um endpoint Model Context Protocol que expõe os produtos da sua conta como ferramentas tipadas (~54 tools) para Claude Code, Cursor e qualquer client MCP: perguntar à wiki, buscar nos vetores, rodar SQL governado, listar/assinar arquivos do storage, inspecionar o cache. O agente trabalha com seus dados — sem credencial de banco em prompt — e cada chamada passa por token com escopo, RBAC por usuário e SQL guard.

Conectar em 1 comando#

bash 
claude mcp add --transport http catcher-data \
  https://data-api.catcher.one/v1/mcp \
  --header "Authorization: Bearer ctc_mcp_SEU_TOKEN"

Qualquer client compatível funciona: a autenticação é Authorization: Bearer com um token MCP (abaixo). Um 401 devolve o Protected Resource Metadata (RFC 9728), então clients modernos descobrem sozinhos como autenticar.

O manifest é o contrato#

bash 
curl -s https://data-api.catcher.one/v1/mcp/manifest -H "X-API-Key: ctc_…"

Retorna o endpoint, o connect_hint (o comando pronto acima), o catálogo de scopes e a lista de tools — cada tool com name, scope exigido e description. O Console (página MCP) mostra o mesmo catálogo.

Tokens MCP (PAT por usuário)#

Tokens do MCP são separados das API keys: prefixo ctc_mcp_, emitidos por usuário, com escopos e TTL opcional.

bash 
KEY="X-API-Key: ctc_…" ; B=https://data-api.catcher.one ; JS='Content-Type: application/json'

# mintar (o segredo aparece UMA única vez)
curl -sX POST $B/v1/mcp/tokens -H "$KEY" -H "$JS" \
  -d '{ "label": "claude-code", "scopes": ["wiki:read","vec:read","db:read"], "expires_in_days": 30 }'
# → { "id": 7, "token": "ctc_mcp_…", "scopes": [...], ... }

curl -s $B/v1/mcp/tokens -H "$KEY"            # listar (label, last4, escopos, último uso, status)
curl -sX DELETE $B/v1/mcp/tokens/7 -H "$KEY"  # revogar — efeito imediato

Escopos#

Escopo Libera
wiki:read / wiki:write ask, search, get/list de páginas / upsert, delete, ingestão, refinery
vec:read / vec:write busca e listagens / criar coleção, adicionar docs, ingerir
db:read / db:write db_run_sql read-only / escrita (DDL continua sujeito ao guard)
store:read / store:write listar, stat, URL assinada / upload, delete
cache:read inspeção do cache

Um token só enxerga as tools cujos escopos carrega — o resto nem aparece na listagem de tools daquele token.

RBAC por usuário (overrides)#

Além dos escopos do token, o owner/admin pode liberar ou bloquear um escopo para um usuário específico — e deny sempre vence:

bash 
curl -sX PUT $B/v1/mcp/grants -H "$KEY" -H "$JS" \
  -d '{ "user_id": 12, "scope": "db:read", "effect": "deny" }'
curl -s "$B/v1/mcp/grants?user_id=12" -H "$KEY"
curl -sX DELETE "$B/v1/mcp/grants?user_id=12&scope=db:read" -H "$KEY"

Camadas de defesa#

  1. Escopo do token — wiki:read não escreve, nunca.
  2. RBAC por usuário — deny vence allow; auditável no Console.
  3. SQL guard — db_run_sql nasce read-only; escrita/DDL são liberações explícitas; GRANT, REVOKE e CREATE USER são bloqueados SEMPRE.
  4. Isolamento de conta/tenant — o token carrega a empresa; ids forjados de outra conta resolvem 404 (validado pela suite de pentest, incluindo os fluxos do MCP).

Boas práticas#

  • Um token por agente/ferramenta, com o menor conjunto de escopos que resolve — revogação cirúrgica quando precisar.
  • Use TTL (expires_in_days) para agentes experimentais.
  • Prefira wiki_ask/vec_search a db_run_sql quando a pergunta é de conhecimento — resposta melhor, superfície menor.
  • O guia completo de tools por produto está nas páginas de cada módulo: Wiki · Vector · Database · Storage · Cache.