Pular para o conteúdo principal

Servidor MCP

O CentralOps expõe suas ferramentas de operação pelo Model Context Protocol em um único endpoint, dentro da própria API:

POST https://centralops.example.com/api/mcp
Authorization: Bearer copsk_SUA_CHAVE

Não há processo separado, container nem porta extra: é o mesmo servidor, o mesmo certificado e a mesma trilha de auditoria da API REST.

Configurar o cliente​

Crie uma chave em Conta › Tokens de API (ela aparece uma única vez) e use a forma remota do seu cliente:

{
  "mcpServers": {
    "centralops": {
      "url": "https://centralops.example.com/api/mcp",
      "headers": { "Authorization": "Bearer copsk_SUA_CHAVE" }
    }
  }
}

No Claude Code:

claude mcp add --transport http centralops https://centralops.example.com/api/mcp --header "Authorization: Bearer copsk_SUA_CHAVE"

A página Conta de cada usuário mostra esse snippet já com a URL da sua instância e diz se o servidor está ligado e se o seu papel tem a permissão necessária.

Quem pode usar​

Três coisas precisam estar verdadeiras, nesta ordem:

  1. O servidor está ligado. Vem desligado. Um admin de plataforma liga em Configurações › Assistentes (MCP). Desligado, /api/mcp responde 404 para todo mundo.
  2. A chave é de um analista com mcp.use. Operator, Engineer e Admin têm por padrão; Viewer não. Um token emitido com scopes restritos precisa incluir mcp.use.
  3. A chave é enviada como Authorization: Bearer. Cookie de sessão do console não é aceito. Isso é de propósito: um endpoint que aceitasse cookie viraria alvo de CSRF por qualquer página que o navegador visitasse.

Para tirar o acesso de alguém, revogue a chave dele ou desative o usuário. Não existe um cadastro separado de "usuários do MCP".

O que o assistente pode fazer​

Exatamente o que o analista pode fazer pelo REST com a mesma chave — nem mais, nem menos.

Cada ferramenta é implementada como uma chamada à API REST, executada dentro do servidor em nome do analista. A permissão da rota, o escopo de organização e os tetos de página são os do REST. Um Operator com mcp.use que pede ao assistente para publicar um mapping recebe o mesmo 403 que receberia com curl, e a ferramenta devolve esse erro ao modelo de forma estruturada (error_kind: upstream_http_error, http_status: 403).

Doze ferramentas alteram estado e são anunciadas ao cliente como tal (readOnlyHint: false): commit_mapping, commit_mapping_patch, request_backfill, cancel_backfill_job, reprocess_quarantine e as sete de enriquecimento (create_enrichment_policy, commit_enrichment_policy, set_enrichment_policy_enabled, rollback_enrichment_policy, set_enrichment_policy_template, apply_enrichment_template e update_enrichment_source_sharing). As de commit exigem um ack_token emitido por um dry-run do mesmo analista, válido por 5 minutos e de uso único. Todas as outras só leem — inclusive dry_run_mapping, dry_run_enrichment e preflight_enrichment_template, que são POST mas não persistem nada.

Enriquecimento​

O assistente enxerga o enriquecimento de ponta a ponta: catálogo, fontes (sem a credencial — a API só diz se ela existe), tabelas (sem as linhas), políticas com as regras vigentes e o histórico, a prontidão por organização, os contadores por regra e o registro das chamadas aos provedores com o erro devolvido por eles. Para uma pergunta como "o enriquecimento parou neste cliente?", a ordem é get_enrichment_readiness, depois get_enrichment_metrics e list_enrichment_activity.

Na escrita, ele cria, publica, liga, reverte e aplica o modelo da matriz às filhas. Credencial e endpoint de fonte não passam pelo MCP: cadastrar e rotacionar chave fica na interface, para o segredo não trafegar pela conversa com o modelo. Pelo MCP dá para mudar só quem usa a fonte (update_enrichment_source_sharing). Todas as rotas de enriquecimento exigem papel admin.

Auditoria​

Toda chamada de ferramenta gera uma linha mcp.tool_call no log de auditoria com o usuário do analista, a ferramenta, o resultado e a duração — mais as linhas normais das rotas REST que a ferramenta chamou, com o mesmo usuário e um User-Agent que identifica o tráfego como MCP (centralops-mcp-embedded/...). Tentativas recusadas (servidor desligado, chave inválida, sem mcp.use) geram mcp.denied.

Transporte​

  • Streamable HTTP, sem sessão: cada POST é autossuficiente e qualquer réplica da API responde. GET e DELETE devolvem 405.
  • Resposta em application/json por padrão. O admin pode trocar para SSE (text/event-stream) na mesma tela; a troca vale na requisição seguinte.
  • O rate limit da chave (60 requisições por minuto) é cobrado uma vez por chamada MCP, mesmo quando a ferramenta faz várias chamadas REST internas.
  • Corpo máximo de 2 MiB por requisição. wait_for_backfill_job espera no máximo 120 s por chamada — proxies reversos costumam cortar acima disso; chame de novo para continuar esperando.

Dicas para o modelo​

O servidor entrega, no initialize, instruções que dizem qual ferramenta responde qual pergunta, como interpretar uma lista vazia em chave de escopo global (organization_id é obrigatório para dados de tenant) e o fluxo incremental para editar mappings grandes sem carregar o array inteiro no contexto. O cliente as mostra ao modelo automaticamente; nada a configurar.