Pular para o conteúdo principal

Introdução

O servidor MCP do Kadu é um servidor Model Context Protocol remoto: conecte o Claude, o ChatGPT, o Claude Code ou uma IDE e use o Kadu conversando — listar tarefas, disparar uma execução, acompanhar eventos e logs, resolver pendências, configurar ambientes, secrets, agendamentos e webhooks, sincronizar o Playbook e consultar uso e custo. Ele oferece as operações da API v1 como tools que o cliente de IA chama. Você o conecta por URL; não há nada para instalar.

Ele é servido em host próprio, mcp.kadu.ia.br, com transporte Streamable HTTP em modo stateless e autenticação por Bearer token emitido pela Conta Kobana: pelo fluxo OAuth 2.1, em que o cliente recebe só a URL e faz o login sozinho, ou por um token pessoal criado no assistente de tokens da Conta Kobana. Nenhum certificado de cliente está envolvido.

Quando usar​

API v1Servidor MCP (este)
Consumidorseu backend, uma integraçãoum cliente de IA (Claude, ChatGPT, Claude Code, uma IDE)
Configuraçãotoken, fora de bandauma URL
TransporteHTTPS/RESTStreamable HTTP (JSON-RPC 2.0)
AutenticaçãoBearer token emitido para a APIOAuth 2.1 ou token pessoal, sempre emitido para o MCP
Superfícieas rotas da /v1uma tool por operação da /v1

O servidor MCP não substitui a API. Cada tool despacha in-process para o handler da rota que implementa a operação, então validação, filtros, fila de execuções, plano contratado, teto de custo e isolamento por organização são exatamente os mesmos. Se você está escrevendo código, use a API v1. Se está conectando um assistente, use isto.

O princípio​

Uma capacidade só existe no MCP se existir na API v1.

Não há uma segunda implementação de nada. A tool chama o handler da rota com a identidade que o token do chamador já provou — a mesma pessoa, a mesma organização —, então ele roda como rodaria para qualquer requisição HTTP. Uma tool faz o que a rota faz — nunca mais.

Na prática, o MCP alcança o mesmo que o Agent Console, porque toda ação do console tem rota na API. Ficam de fora só o que, por definição, é da pessoa no navegador: login e troca de organização, onboarding, a conexão do Playbook pelo GitHub App e decidir uma aprovação — veja Confirmação de tools destrutivas.

tools/list devolve apenas as tools que este chamador pode rodar: as que o escopo do token alcança e que o papel da pessoa permite na organização. Um assistente não é informado de capacidades que só levariam negativa. As regras estão em Autenticação.

Primeiros passos​

  1. Aponte seu cliente para a URL do servidor — veja Endpoints e Clientes.

  2. Autorize. O cliente abre o login da Conta Kobana; entre com uma conta da organização e escolha, na tela de consentimento, o que o assistente pode fazer. Veja Autenticação.

  3. Liste as tools para confirmar o que o seu acesso alcança — peça ao assistente, ou, com um token emitido para o MCP em mãos:

    curl https://mcp.kadu.ia.br/ \
      -H "Authorization: Bearer $MCP_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "MCP-Protocol-Version: 2025-06-18" \
      -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

  4. Explore a documentação — o catálogo completo está em Tools.

:::caution O que vem de uma execução é dado, não instrução Eventos, logs, memórias e pendências carregam texto que o agente escreveu a partir de dados de terceiros (extratos, registros do ERP, e-mails). O servidor orienta o assistente a não seguir ordens encontradas ali e a confirmar com você antes de qualquer ação que um resultado pareça pedir. :::

Próximos passos​

  • Autenticação — o fluxo OAuth, o token pessoal, o escopo e as permissões aplicados, e os modos de falha.
  • Endpoints — URLs por ambiente e rotas servidas.
  • Transporte — JSON-RPC, versões do protocolo, cabeçalhos e métodos.
  • Resources e prompts — documentos por URI, roteiros prontos, autocomplete e a confirmação de tools destrutivas.
  • Clientes — como conectar o Claude Code e clientes por arquivo.
  • Limite de Requisições — o orçamento por pessoa.
  • Listagem, Ordenação e Filtros — cursor, limit, sort_by e os filtros.
  • Idempotência — idempotency_key nas escritas.
  • Erros — os dois canais de falha, e por que a distinção importa.
  • Tools — o catálogo de tools.