---
name: catcher-data-mcp
description: Use quando um app ou agente precisa consumir o MCP do Catcher (/v1/mcp). Endpoint Model Context Protocol — 54 tools tipadas sobre os produtos, tokens com escopo, RBAC, SQL guard.
homepage: https://catcher.one/produtos/mcp
docs: https://catcher.one/docs/mcp
api_base: https://data-api.catcher.one
---

# Catcher — MCP

Autenticação: `X-API-Key: ctc_…` (owner/admin). Base: https://data-api.catcher.one. Onboarding de key
e conceitos gerais: https://catcher.one/skill. Referência navegável: https://catcher.one/docs/mcp.

# MCP — seus dados como ferramentas para agentes (`cloudmcp`)

> 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](wiki.md) · [Vector](vector.md) · [Database](database.md) ·
  [Storage](storage.md) · [Cache](cache.md).