Autenticação

O servidor MCP autentica pelo token no cabeçalho Authorization: sem cookie e sem certificado de cliente.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs…

:::warning Nunca na URL nem no corpo Token na query string (?access_token=…) ou no corpo da requisição não autentica: a resposta é 401. Um token na URL vaza em logs de proxy e de CDN, no Referer e no histórico do navegador. O documento de metadata anuncia bearer_methods_supported: ["header"], e o servidor faz valer o anúncio. :::

Os tokens aceitos

Token	Como você obtém	Validade	Para quem
OAuth	Você cola a URL no cliente, e ele abre a tela de login e consentimento da Kobana	30 minutos, renovado sozinho pelo cliente	Claude, ChatGPT, IDEs e qualquer cliente que faça o fluxo OAuth do MCP
Pessoal	Você cria em Conta Kobana → Tokens e Acesso → Meus Tokens Pessoais → Novo Token, com o aplicativo Gateway Bancário e o uso MCP, e cola no cliente	A que você escolher: 7 dias, 30 dias, 3 meses, 6 meses, 1 ano ou uma data até 1 ano	Script, CLI ou agente próprio que não faz o fluxo OAuth

Os dois são verificados do mesmo jeito em toda requisição. Prefira o OAuth sempre que o cliente suportar: ele vale por pouco tempo e fica atrelado a uma autorização que você revoga sem afetar mais nada.

O token pessoal criado para API REST tem outra audience e é recusado aqui com 401. Também recebem 401:

token emitido para outro serviço da Kobana (o Inbox, o Financeiro);
token de aplicação OAuth de terceiro sem resource, como o de uma integração REST: ele foi consentido para a API, não para um agente;
token expirado ou revogado.

:::info Tokens de API antigos Tokens criados antes do wizard de token pessoal, sem resource e sem aplicação OAuth por trás, também são aceitos. Um token da conta, que não nomeia nenhuma pessoa, vale só pelo escopo, como na API REST: não há permissão de pessoa para estreitar. Para um agente, prefira o token pessoal com uso MCP, que tem validade e escopo por recurso. :::

O fluxo OAuth

Você não executa nenhum destes passos: o cliente MCP faz tudo sozinho a partir da URL. Eles estão aqui para quando algo falhar no meio.

Desafio. Uma requisição sem token recebe 401 com o cabeçalho que aponta para a metadata do recurso (RFC 9728):
```
WWW-Authenticate: Bearer resource_metadata="https://mcp.banking.kobana.com.br/.well-known/oauth-protected-resource"
```
Quando um token foi enviado e não serve, o cabeçalho traz também error="invalid_token" e, quando há, a error_description.

Metadata do recurso. O cliente lê o documento apontado. Ele é público e não carrega segredo, só ponteiros:

curl https://mcp.banking.kobana.com.br/.well-known/oauth-protected-resource

{
  "resource": "https://mcp.banking.kobana.com.br",
  "resource_name": "Kobana MCP",
  "authorization_servers": ["https://account.kobana.com.br"],
  "scopes_supported": ["banking/charge.bank_billets", "banking/charge.pix", "…", "read"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://docs.kobana.com.br"
}

Metadata do authorization server (RFC 8414), em https://account.kobana.com.br/.well-known/oauth-authorization-server. Ela anuncia PKCE com S256, cliente público (token_endpoint_auth_methods_supported com none), registro dinâmico e Client ID Metadata Document.
Identificação do cliente. O cliente se identifica por um dos três caminhos da próxima seção.
Autorização com PKCE e resource (RFC 8707). O navegador abre a tela de consentimento da Kobana. Você entra, escolhe a conta, os recursos e o nível de acesso, e autoriza.
Token. O cliente troca o código por um access token de 30 minutos, vinculado a este servidor, e o renova com refresh token quando expira.

O token carrega quem autorizou e a conta autorizada. É a conta que escopa os dados: nenhuma tool aceita conta como argumento.

Como o cliente se identifica

Caminho	O que é	Quando usar
Client ID Metadata Document (CIMD)	O `client_id` é a URL de um documento publicado pelo próprio cliente, como a identidade publicada do Claude	O padrão, e o recomendado: não há nada a cadastrar
Registro dinâmico (RFC 7591)	O cliente se registra sozinho no authorization server	Clientes que ainda não suportam CIMD
Cliente cadastrado	`client_id` cadastrado pela Kobana	Integração própria, com escopos combinados com a Kobana

Deixe o client secret em branco. O cliente MCP é público e não tem onde guardar segredo: quem prova a posse do código de autorização é o PKCE.

Leitura para todos, escrita para quem foi verificado

O que um cliente pode receber depende de alguém da Kobana saber quem ele é:

Cliente	Pode receber
Registrado dinamicamente, ou CIMD de uma origem que a Kobana não conhece	Os escopos `banking/<recurso>` e `read`. Só leitura.
CIMD de uma origem conhecida, como a identidade publicada do Claude	Também `write`, quando pede
Cadastrado pela Kobana	Os escopos combinados no cadastro

A metadata do recurso anuncia em scopes_supported só os escopos que qualquer cliente pode receber: os banking/<recurso> e read. Um cliente que segue a descoberta sozinho conecta, portanto, só para leitura. Para escrever, o cliente precisa pedir write explicitamente, e na tela de consentimento você escolhe se concede.

Escopo do token

O escopo é o teto do cliente. Toda tool pertence a um recurso, e o token precisa carregar, para esse recurso:

o recurso: o escopo banking/<recurso> (por exemplo, banking/charge.bank_billets), o nome legado do mesmo recurso (charge.bank_billets) ou all;
o nível de acesso: read ou write para uma tool de leitura; write para qualquer outra, destrutivas incluídas.

Escopo do token	Resultado
`banking/charge.bank_billets read`	Lê boletos de cobrança, e nada mais
`banking/charge.bank_billets banking/charge.pix write`	Lê e opera boletos e cobranças Pix
`banking/payment.pix read`	Lê pagamentos Pix, e não paga nada

O escopo de cada família de tools está no catálogo.

:::caution banking/all não dá escrita No token pessoal, "todos os recursos" (banking/all) é só leitura: o wizard desmarca os acessos de escrita quando você escolhe essa opção. Para um agente que escreve, marque recurso por recurso. :::

Permissão de quem autorizou

Por cima do escopo vale a permissão da pessoa que autorizou o cliente ou criou o token pessoal. O agente só faz o que essa pessoa pode fazer na tela correspondente do painel: consultar boletos, emitir, cancelar, aprovar pagamentos, transferir. Onde o painel exige duas permissões para uma ação, a tool exige as mesmas duas. A permissão de cada tool está no catálogo.

Situação	Resultado
A pessoa tem a permissão	A tool roda, se o escopo também deixar
A pessoa não tem a permissão	A tool não aparece em `tools/list`, e a chamada é recusada com `insufficient_permission`
A pessoa foi desativada ou não é mais usuária da conta	Nada é alcançado: `membership_inactive`
A pessoa é master da conta-mãe e opera uma subconta	Vale como usuária da subconta

A permissão é relida a cada chamada. Tirar uma permissão no painel vale na chamada seguinte, sem esperar o token expirar. Revogar o token também vale na hora: o servidor recusa token revogado em toda requisição.

:::tip Postura recomendada para agentes Autorize o cliente com um usuário que tenha só as permissões de que o agente precisa. Um cliente autorizado por um usuário somente-leitura expõe só as tools de leitura, faça o que fizer o modelo do outro lado. Para uso exploratório, conceda só read. :::

O plano da conta

O plano não esconde tools: uma tool de um produto que a conta não contratou continua em tools/list, e a chamada responde product_not_enabled. Quem resolve é a contratação do produto, não um escopo ou uma permissão.

Quem resolve cada recusa

As recusas de autorização voltam como resultado de tool com isError, não como erro HTTP, para que o modelo leia e explique. Cada código aponta para quem resolve:

`code`	Quem resolve
`insufficient_scope`	Quem conectou o cliente: autorizar de novo com o recurso ou o nível de acesso que falta
`insufficient_permission`	O administrador da conta: conceder a permissão de painel
`membership_inactive`	O administrador da conta: reativar o usuário
`product_not_enabled`	A contratação: incluir o produto no plano da conta

Modos de falha HTTP

HTTP	Causa
`401`	Token ausente, malformado, expirado, revogado, emitido para outro recurso, de aplicação de terceiro, ou fora do cabeçalho `Authorization`
`403`	API desabilitada na conta, conta bloqueada, conta sem assinatura ativa (em produção) ou IP fora da allow list da conta. Também `Host` ou `Origin` fora da allowlist do servidor, este como erro JSON-RPC `-32600`
`429`	Limite de requisições: veja Limite de requisições

Todo 401 carrega o WWW-Authenticate com o ponteiro para a metadata, que manda o cliente de volta ao fluxo OAuth. O 403 de conta não carrega: nenhuma nova autenticação resolve uma conta bloqueada.

O corpo do 401, como o do 403 de conta, é o mesmo da API REST, em português:

{ "status": 401, "errors": [{ "title": "Token de API inválido (Servidor: production)", "code": "unauthorized", "detail": "…" }] }

Os tokens aceitos​

O fluxo OAuth​

Como o cliente se identifica​

Leitura para todos, escrita para quem foi verificado​

Escopo do token​

Permissão de quem autorizou​

O plano da conta​

Quem resolve cada recusa​

Modos de falha HTTP​