Skip to main content

Introduction

The Smart Finance MCP server is a remote Model Context Protocol server that exposes the public API's operations — payables and receivables, transactions, reconciliations, financial accounts, cash flow and registers — as tools an AI client can call. You connect it by URL; there is nothing to install.

It is served on its own host, mcp.finance.kobana.com.br, on the same domain as the API, with Streamable HTTP transport in stateless mode and authentication by a Bearer token issued for the MCP by the Kobana Account. No client certificate is involved.

:::info Availability The server, its 95 tools, the resources and the prompts are implemented, and authentication goes through the Kobana authorization server: through the OAuth 2.1 flow, in which the client gets only the URL and signs in on its own, or through a personal token created on your Kobana Account. The dedicated edge (the mcp.finance.* distribution, WAF and DNS) is still being provisioned. :::

When to use it​

REST API (/v1)MCP server (this)
Consumeryour backendan AI client (Claude, ChatGPT, an IDE)
Setuptoken and X-Workspace-Id, out of bandjust a URL; the workspace goes in each call
TransportHTTPS/RESTStreamable HTTP (JSON-RPC 2.0)
AuthenticationBearer token issued for the APIOAuth 2.1 or personal token, always issued for the MCP
Authorizationtoken scopetoken scope and the person's permissions
Surfacethe /v1 endpoints95 tools, one per operation of those endpoints, plus resources and prompts on top of them

The MCP server does not replace the REST API. Each tool dispatches in-process to the endpoint that implements the operation, so filters, validation, settlement rules, rateio and workspace isolation are exactly the same. If you are writing code, use the REST API. If you are connecting an assistant, use this.

The principle​

A capability exists in MCP only if it exists in the public API.

Nothing is implemented twice. The tool calls the endpoint's handler with the identity the caller's token has already proven — the same person, the same organization, the same workspace —, so it runs, checks the scope and audits as it would for any HTTP request. A tool does what the endpoint does over REST — never more.

In practice: what today exists only in the dashboard (approving payments, importing statements, managing members) does not become a tool before it becomes an endpoint.

What you see is narrower than the catalogue​

tools/list returns only the tools this caller can run: the ones the token's scopes reach and the token's person is allowed to do in the organization. An agent is not told about capabilities it would only be denied. Both axes are in Authentication.

Getting started​

  1. Point your client at the server URL — https://mcp.finance.kobana.com.br, nothing else. See Endpoints and Clients.

  2. Authorize. The client opens the Kobana login; sign in with an account of the organization and authorize the access. See Authentication.

  3. Pick the workspace. The agent calls finance_workspaces_list and passes the chosen id as workspace_id to the other tools. If you reach only one workspace, it is the default and the argument can be left out. See Authentication → The workspace.

  4. List the tools to confirm what your access reaches — ask the assistant, or, with a token issued for the MCP in hand:

    curl https://mcp.finance.kobana.com.br/ \
      -H "Authorization: Bearer $MCP_TOKEN" \
      -H "Content-Type: application/json" \
      -H "MCP-Protocol-Version: 2025-06-18" \
      -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

  5. Browse the catalogue in Tools.

Next steps​

  • Authentication — the OAuth flow, the personal token, the workspace, the scope and permissions applied, and the failure modes.
  • Endpoints — URLs per environment and the routes served.
  • Transport — JSON-RPC, headers and methods.
  • Clients — how to connect Claude Code and file-configured clients.
  • Listing, filters and fields — cursor, filters, sort_by, fields.
  • Idempotency — and the actions that move money.
  • Resources and prompts — documents by URI, ready-made scripts, autocomplete and the confirmation of destructive tools.
  • Errors — the two failure channels, and why the distinction matters.
  • Tools — the full catalogue.