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 and the client discovers on its own where to authenticate, opens the Kobana login in the browser and stores the token. See Authentication.

A client without OAuth support connects too, with a personal token: create it under Kobana Account → Tokens and Access → New Personal Token, with the Smart Finance app and the MCP usage, and configure the client to send it in the Authorization: Bearer <token> header. It is also the path for an agent that needs to write, since through the OAuth flow access is read-only today.

The URL carries no workspace. The agent picks where to act on every call: finance_workspaces_list lists the workspaces you reach, and the other tools take workspace_id. If you reach only one, not even that is needed. To pin a default workspace on the connection, add ?workspace_id= to the URL or, when the client allows it, the X-Workspace-Id header — both are optional. See Authentication → The workspace.

Claude Code​

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

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

To set a default workspace — optional —, use the URL with it:

claude mcp add --transport http kobana-finance \
  "https://mcp.finance.kobana.com.br/?workspace_id=$WORKSPACE_ID"

With a personal token, without the OAuth flow:

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

File-configured clients​

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-finance": {
      "type": "http",
      "url": "https://mcp.finance.kobana.com.br"
    }
  }
}

On the first connection the client opens the browser for you to authorize. You pick the organization on the consent screen, and it is recorded in the token; the workspace comes from each call (or from the default, if you put ?workspace_id= on the URL).

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

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

For a default workspace, add "X-Workspace-Id": "<uuid>" to headers — optional.

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.finance.kobana.com.br, nothing else — into their connector settings. The OAuth flow runs inside the app itself, and the assistant discovers the workspaces on its own, with finance_workspaces_list.

Using Billing alongside​

This server's tools start with finance_, and those of Automatic Billing with billing_; the resources, with kobana://finance/ and kobana://billing/. Both servers live in the same client without collisions — connect both when the agent needs both ends.

  • Authorize with the right account. MCP narrows the tools to what the person who authorized can do in the dashboard. A client authorized by a read-only analyst exposes only the read tools, whatever the model on the other side does. It is the strongest way to restrict an agent.
  • One token per client. Each client runs its own flow and gets its own token, which only works on the MCP — it cannot be used to call the REST API. To switch off an agent, remove its authorization on Kobana without affecting your integrations.
  • Personal token: short validity and minimum scope. Check only the resources and access the agent needs, and the shortest validity the use allows: revoking the token on Kobana does not cut access before it expires — see Personal token revocation. An agent that records bills does not need finance/payable_dispatches.
  • Keep the MCP channel closed for paying. By default, Security › Channels does not let AI agents send to the bank. Open it only on purpose.
  • Start in sandbox. The server asks for confirmation on destructive tools, but the first exploration should not be in production.
  • Destructive tools need a client that confirms. Deleting, sending to the bank, charging, transferring, reconciling or adjusting a balance only runs in a client that speaks the 2026-07-28 revision with form elicitation; in any other, those tools return confirmation_required and everything else works as usual. See Confirming destructive tools.

Checking the connection​

The simplest way is to ask the assistant: "which workspaces can you act on?" — it calls finance_workspaces_list. Then, "which companies exist in the Matriz workspace?" calls finance_companies_list with its workspace_id.

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

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

# The workspaces the token's person reaches
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"finance_workspaces_list","arguments":{}}}'

# The companies of one workspace
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"finance_companies_list",
                 "arguments":{"workspace_id":"'"$WORKSPACE_ID"'","fields":["name","cnpj"]}}}'

If the number of tools is lower than you expected, it is the permissions of whoever authorized or the token's scope — see Authentication. It is not an error.