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.

1. Desafio. Uma requisição sem token recebe 401 com o cabeçalho que aponta para a metadata do recurso (RFC 9728):

   WWW-Authenticate: Bearer realm="banking-mcp", error="invalid_token", resource_metadata="https://mcp.banking.kobana.com.br/.well-known/oauth-protected-resource"

   O error="invalid_token" vem também quando nenhum token foi enviado. Quando um token foi enviado e não serve, o cabeçalho traz ainda, quando há, a error_description.

2. 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"
   }

3. 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.

4. Identificação do cliente. O cliente se identifica por um dos três caminhos da próxima seção.

5. 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.

6. 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 Origin de outro site (origin_not_allowed) e Host 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.

Sem token, o corpo do 401 diz o que falta e aponta para esta página. Com um token que não existe, o code é o mesmo e a mensagem diz que o token não vale:

{ "error": { "code": "invalid_token", "message": "Missing Bearer token. Use Authorization: Bearer <access token>.", "documentation_url": "https://docs.banking.kobana.com.br/mcp/overview/authentication" } }

Com um token que existe mas não serve (expirado, revogado, emitido para outro recurso, de aplicação de terceiro, ou fora do cabeçalho), o corpo do 401, como o do 403 de conta, é o mesmo da API REST, em português:

{ "status": 401, "errors": [{ "title": "O token de acesso (access token) está expirado.", "code": "unauthorized" }] }

O 403 de Origin tem corpo próprio, { "error": { "code": "forbidden", "message": "origin_not_allowed" } }: veja Transporte.