Introdução

O servidor MCP do Dashboard Mágico é um servidor Model Context Protocol remoto que expõe as operações da API pública — organização, usuários do portal e equipe — como tools que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar.

Ele é servido em host próprio, mcp.dashboards.kobana.com.br, com transporte Streamable HTTP em modo stateless e autenticação por Bearer token. Nenhum certificado de cliente está envolvido.

:::info Disponibilidade O servidor e suas 292 tools estão implementados, e a autenticação é pelo authorization server da 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 na sua conta Kobana. A borda dedicada (distribution mcp.dashboards.*, WAF e DNS) ainda está sendo provisionada. :::

Quando usar

	API REST (/v1)	Servidor MCP (este)
Consumidor	seu backend	um cliente de IA (Claude, ChatGPT, uma IDE)
Configuração	token, fora de banda	uma URL
Transporte	HTTPS/REST	Streamable HTTP (JSON-RPC 2.0)
Autenticação	Bearer token emitido para a API	OAuth 2.1 ou token pessoal, sempre emitido para o MCP
Superfície	177 rotas	292 tools sobre os mesmos endpoints

O servidor MCP não substitui a API REST. Cada tool despacha in-process para o endpoint que implementa a operação, então filtros, regras de upsert, validação, proração e isolamento por organização são exatamente os mesmos. Se você está escrevendo código, use a API REST. Se está conectando um assistente, use isto.

O princípio

Uma capability só existe no MCP se existir na API pública.

Não há uma segunda implementação de nada. A tool chama o handler do endpoint 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, e a auditoria que grava é atribuída a quem autorizou o cliente. Uma tool faz o que o endpoint faz por REST — nunca mais.

A consequência prática: o que hoje só existe no dashboard não vira tool antes de virar endpoint.

O que você vê é mais estreito que o catálogo

tools/list devolve apenas as tools que este chamador pode rodar, filtradas pelas permissões de dashboard de quem autorizou o cliente. Um agente 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 Kobana; entre com uma conta da organização e autorize o acesso. 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.dashboards.kobana.com.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.

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, cabeçalhos e métodos.
• Resources e prompts — documentos por URI, roteiros prontos, autocomplete e a confirmação de tools destrutivas.
• Clientes — como conectar Claude Code e clientes por arquivo.
• Listagem, ordenação e campos — page, sort_by, fields.
• Erros — os dois canais de falha, e por que a distinção importa.
• Tools — o catálogo das 292 tools.