Conectar

Como conectar ao servidor MCP da Minha CNH — blocos prontos para Claude Code, Cursor e VS Code, API key server-to-server ou OAuth por usuário para clientes de IA desktop (Claude Desktop, Claude Cowork, ChatGPT).

Há duas formas de conectar ao servidor MCP: com a API key da organização (server-to-server, o backend/agente da sua organização usando a mesma chave da API REST) ou via OAuth por usuário, para clientes de IA desktop como Claude Desktop, Claude Cowork e ChatGPT — ver Conexão OAuth.

Antes de ter uma credencial

O catálogo de ferramentas é público: tools/list responde sem Authorization, então dá para inspecionar todos os nomes e schemas antes de pedir uma API key ou fechar contrato.

curl -X POST "https://minhacnh.doutormultas.com.br/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

initialize e ping também respondem sem credencial — só tools/call exige Authorization.

Conectar com API key

Cole o bloco do seu cliente. O endpoint e a credencial são sempre os mesmos; muda só onde eles entram — um comando no terminal ou um arquivo de configuração.

Um comando, no terminal:

claude mcp add --transport http minha-cnh https://minhacnh.doutormultas.com.br/api/mcp \
  --header "Authorization: Bearer cnh_live_<prefix>_<secret>"

Sem --scope, o servidor vale só para o projeto atual; use --scope user para todos os seus projetos. Rode /mcp dentro do Claude Code para confirmar que o servidor aparece como connected — credencial inválida aparece como failed.

Para versionar a configuração no repositório do time, use --scope project (grava um .mcp.json) e deixe a chave numa variável de ambiente, em vez de commitá-la:

{
  "mcpServers": {
    "minha-cnh": {
      "type": "http",
      "url": "https://minhacnh.doutormultas.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer ${MINHA_CNH_API_KEY}"
      }
    }
  }
}

A execução exige autenticação

tools/call exige Authorization: a API key cnh_live_<prefix>_<secret> no caminho server-to-server, ou o token OAuth no caminho desktop. Sem credencial válida a chamada falha com erro de autenticação (ver Erros) — e é no tools/call que o billing e o acesso aos dados são aplicados. Os schemas de cada ferramenta estão em Ferramentas.

A API key é da organização, não da pessoa

Qualquer um desses blocos dá ao cliente de IA a mesma chave que o seu backend usa: os créditos consumidos e os rate limits são os da organização. Em máquinas de desenvolvedor, prefira as formas que mantêm a chave fora do arquivo versionado (${MINHA_CNH_API_KEY} no Claude Code, inputs no VS Code) e rotacione a chave em Autenticação se ela vazar.

Conexão OAuth (clientes desktop)

Clientes de IA desktop — Claude Desktop, Claude Cowork, ChatGPT — não guardam uma API key de organização e esperam o fluxo moderno de conector MCP. Para esses, o servidor também aceita OAuth 2.1 (com PKCE e registro dinâmico de cliente): basta colar o endpoint como um conector e autenticar.

No cliente, adicione um conector MCP personalizado apontando para https://minhacnh.doutormultas.com.br/api/mcp (no Claude Desktop: Configurações → Conectores → Adicionar conector personalizado).
O cliente descobre o servidor de autorização automaticamente e abre o login da Minha CNH.
Depois do login, você escolhe qual das suas organizações (com API habilitada) o assistente vai usar — é essa organização que consome créditos e cujos limites se aplicam. Se você só tem uma organização elegível, o passo é pulado.
Pronto — o assistente chama as mesmas ferramentas, com o mesmo billing e rate limits da API key.

Uma organização por usuário

Cada usuário liga o conector a uma organização de cada vez; reautorizar troca a organização vinculada. Um usuário sem nenhuma organização com API habilitada não consegue concluir o consentimento.

As ferramentas não apareceram no chat?

Se o conector autentica mas as ferramentas não surgem, reconecte — remova e adicione de novo (ou desative e reative o conector). O cliente refaz a descoberta e passa a listar as ferramentas. Confirme também que a organização escolhida tem o acesso à API habilitado.

Gerenciar o acesso

Para desconectar, remova o conector no próprio cliente de IA. Reautorizar com um conector já existente apenas troca a organização vinculada (uma por usuário). Para revogar o vínculo pelo lado do servidor, fale com o suporte.

O caminho de API key acima continua recomendado para integrações server-to-server — backends e agentes que rodam sem um usuário interativo.

Autenticação

Para o caminho server-to-server, é a mesma API key da API REST, no mesmo formato: Authorization: Bearer cnh_live_<prefix>_<secret>. Não existe uma chave separada para MCP. Veja Autenticação para gerar, rotacionar e revogar chaves. Clientes desktop usam o fluxo OAuth em vez da API key.