Skip to main content

Clients

Any client that speaks Streamable HTTP MCP and can run the MCP OAuth 2.1 flow can connect. You only provide the URL; the client discovers where to authenticate on its own, opens the Kobana sign-in in the browser and keeps the token — see Authentication.

A client without OAuth support connects too, with a personal token: create it at Kobana Account → Tokens and Access → New Personal Token, with the Régua de Cobrança app and the MCP usage, and configure the client to send it in the Authorization: Bearer <token> header. A personal token is also the way to let an agent write: clients connected through the OAuth flow are read-only today.

:::warning Sign in to the dashboard first The tools follow the permissions of the person who owns the token in the organization. Someone who has never signed in to the Régua de Cobrança dashboard with their Kobana account gets no tools (key_owner_not_member) — sign in once before connecting a client. :::

Claude Code​

claude mcp add --transport http kobana-dunning https://mcp.dunning.kobana.com.br

Then run /mcp in a session and pick Authenticate to sign in to Kobana.

With a personal token, no OAuth flow:

claude mcp add --transport http kobana-dunning https://mcp.dunning.kobana.com.br \
  --header "Authorization: Bearer <personal token>"

Clients configured by file​

Clients that read a JSON configuration file ask for the URL and the transport. Through the OAuth flow there is no authentication header:

{
  "mcpServers": {
    "kobana-dunning": {
      "type": "http",
      "url": "https://mcp.dunning.kobana.com.br"
    }
  }
}

On the first connection the client opens the browser for you to authorize. There is no organization-selection header: you pick the organization on the consent screen, and it is recorded in the token.

With a personal token, add the header — the organization is the one of the account you created the token in:

{
  "mcpServers": {
    "kobana-dunning": {
      "type": "http",
      "url": "https://mcp.dunning.kobana.com.br",
      "headers": { "Authorization": "Bearer <personal token>" }
    }
  }
}

Treat the file as a secret: whoever reads it uses the token.

Clients that connect by URL​

Claude and ChatGPT connect a remote server by pasting the URL https://mcp.dunning.kobana.com.br into their connector settings. The OAuth flow runs inside the app itself.

  • Authorize with the right account. Tools are narrowed to the dashboard permissions of the person who owns the token. A client authorized by a read-only analyst exposes only the read tools, whatever the model on the other end does. It is the strongest way to restrict an agent.
  • One token per client. Each client gets its own token, which is valid only on MCP — it cannot call the REST API.
  • Personal token: short validity, least scope. Select only the resources and access the agent needs, and the shortest validity the use allows: revoking the token in Kobana does not cut access before it expires — see Personal token revocation.
  • Start in sandbox. Destructive tools send real messages to debtors, report them to credit bureaus and protest their debts. The server asks for confirmation before each one (and refuses them to a client that cannot confirm), but the first exploration should not be in production.

Checking the connection​

The simplest way is to ask the assistant: "which organization am I using in Régua de Cobrança?" — it calls dunning_me, which any valid token can run and which returns the person, the organization, the scopes and the token's expiry.

With a token issued for MCP — a personal token with the MCP usage, for example — you can check with curl:

# 1. Who is this token, and which organization does it reach?
curl -s https://mcp.dunning.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"dunning_me","arguments":{}}}'

# 2. How many tools does this token reach?
curl -s https://mcp.dunning.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools | length'

If the number is lower than you expected, it is the permissions of the person who owns the token or the token scope — see Authentication. It is not an error.