Conectar um agente de IA ao Konektor via MCP

O que o MCP entrega

O servidor MCP do Konektor é stateless, via HTTP streamable (não existe modo local/stdio) e responde em https://app.konektor.com.br/mcp. Hoje ele expõe 72 ferramentas e 10 prompts prontos:

Duas formas de conectar, dependendo do cliente

O Konektor aceita dois jeitos de autenticar no MCP, e o jeito certo depende do cliente:

• Claude.ai (conector web) e Claude Desktop: usam OAuth automaticamente — você entra com sua conta Konektor quando o cliente pedir. Se aparecer um erro de identidade não vinculada, fale com o administrador do seu workspace.
• Claude Code, Codex e outros agentes de terminal ou CI: usam uma credencial pessoal (prefixo kmcp_), enviada como cabeçalho Authorization: Bearer. É esse caminho que este guia cobre a partir daqui — você mesmo emite a chave, sem depender de ninguém vincular sua conta manualmente.

Passo 1 — Emitir sua credencial pessoal

No Konektor Desktop, abra Configurações → Conectar agente. A tela permite emitir, listar e revogar suas próprias chaves — sem passar por suporte ou administrador.

• A chave só aparece por inteiro uma vez, no momento da emissão. Depois disso, a tela mostra apenas os últimos caracteres (o "hint").
• Escopo padrão: analytics:read (leitura). Marcar a opção de propostas adiciona operations:propose.
• Validade padrão de 90 dias, configurável até 365. Passado o prazo, a chave para de funcionar sozinha.
• A tela mostra o último uso de cada chave — útil para notar uma chave esquecida antes de revogar.

Passo 2 — Instalar por agente

Todos os exemplos abaixo usam uma variável de ambiente (KONEKTOR_MCP_TOKEN) em vez da chave colada direto no comando ou no arquivo de configuração — assim o arquivo pode ir para um repositório sem vazar a chave.

Definir a variável no Windows

Permanente (novo terminal em diante):

setx KONEKTOR_MCP_TOKEN "kmcp_cole_sua_chave_aqui"

Só para a sessão atual do PowerShell:

$env:KONEKTOR_MCP_TOKEN = "kmcp_cole_sua_chave_aqui"

Claude Code

claude mcp add --transport http --scope user konektor https://app.konektor.com.br/mcp --header "Authorization: Bearer ${KONEKTOR_MCP_TOKEN}"

Codex (~/.codex/config.toml)

[mcp_servers.konektor]
url = "https://app.konektor.com.br/mcp"
bearer_token_env_var = "KONEKTOR_MCP_TOKEN"

Cliente MCP genérico

Qualquer cliente que aceite Streamable HTTP com cabeçalhos customizados entende este formato:

{
  "mcpServers": {
    "konektor": {
      "url": "https://app.konektor.com.br/mcp",
      "headers": {
        "Authorization": "Bearer ${KONEKTOR_MCP_TOKEN}"
      }
    }
  }
}

Escopos e o que cada credencial vê

Uma credencial pessoal nunca resolve mais acesso do que a própria pessoa tem no Konektor:

• Os escopos pedidos na emissão são sempre cruzados com o papel real do usuário — um viewer continua vendo só analytics:read, mesmo que a chave tenha sido emitida com a opção de proposta marcada.
• Contas Mercado Livre visíveis são as mesmas atribuídas ao usuário no produto — nunca o tenant inteiro para quem não é owner/admin.
• operations:execute e brain:write nunca saem por credencial pessoal, em nenhum papel — essas 10 ferramentas (2 + 8) só respondem no caminho interativo do produto.
• Se a assinatura da consultoria ficar inadimplente, a credencial para de funcionar na chamada seguinte, sem precisar revogar manualmente.

Revogar ou renovar

Na mesma tela Configurações → Conectar agente: revogar encerra o acesso imediatamente — a próxima chamada já recusa a chave. Não existe "revogação agendada".

Antes do vencimento, emita uma chave nova e atualize a variável de ambiente onde o agente roda; depois revogue a antiga. Isso evita um agente ficar sem acesso no meio de uma tarefa.

Quando não conecta

Confira nesta ordem:

1. Cabeçalho exato. Precisa ser Authorization: Bearer kmcp_..., com espaço depois de "Bearer" e sem aspas extras.
2. O cliente está realmente enviando o cabeçalho? Alguns clientes MCP, ao detectar que o servidor também anuncia OAuth, ignoram a Authorization configurada e tentam a descoberta OAuth sozinhos — nesse caso, o agente só enxerga ferramentas sintéticas de autenticação em vez das 72 reais. Confirme a versão do cliente e, se o problema persistir, avise o suporte.
3. Erro mcp_token_auth_disabled: a autenticação por credencial pessoal ainda não foi habilitada neste ambiente. Fale com o suporte.
4. Erro invalid_token: a chave está errada, expirada ou já foi revogada. Emita uma nova na tela Conectar agente.
5. Erro insufficient_scope: a ferramenta chamada exige um escopo que a chave não tem (por exemplo, uma proposta sem operations:propose marcado na emissão). Emita uma nova chave com o escopo certo.
6. Erro rate_limited (HTTP 429): a chave excedeu o limite de chamadas por minuto. O cabeçalho Retry-After traz quantos segundos esperar.
7. Erro de assinatura/cobrança: a consultoria está com a assinatura em atraso além da tolerância. Regularize o pagamento para o acesso voltar.

Se nada disso resolver, escreva para contato.rosiak@gmail.com com o hint da chave (os últimos caracteres mostrados na tela) — nunca a chave completa.