Connecting an MCP
The Model Context Protocol (MCP) lets AI assistants and agents connect to external tools and data. An MCP client that connects to Klart can read and act on a user's Klart data on their behalf — so the authorization has to be user-consented and tightly scoped.
MCP clients connect to Klart as OAuth Connectors. The MCP authorization spec is OAuth 2.1 — the same authorization-code + PKCE + discovery flow documented in Connectors & OAuth. This page covers the MCP-specific details; that page has the full step-by-step.
Two ways to connect your AI
An AI can work with Klart in one of two ways. Both start with the same login and consent screen, and both only reach what you approve.
| Through the MCP server | Through the API | |
|---|---|---|
| Address | https://mcp.klart.com | https://api.klart.com |
| What the AI gets | Ready-made, read-only tools, such as "list accounts" and "search transactions" | The full Klart API, within the roles you grant |
| Can it change data? | No, it can only read | Yes, if the roles you grant allow it |
| Set up by | Pasting one link into your AI (Connect to in Klart) | The AI or its developer, following this page and llms.txt |
| Best for | Asking questions about your data in Claude or Claude Code | Agents and integrations that build their own requests |
| Token | Works only on the MCP server | Works on the API |
If in doubt, use the MCP server. It is read-only by design, needs no setup beyond approving the connection, and every request is tied to you. Choose the API when an agent needs something the tools do not offer, or needs to write.
The rest of this page covers both. Claude Code shows the MCP route; the flow and the shared local connector describe the API route.
How it fits together
An MCP connection is a Connector: when a user authorizes it, Klart mints a scoped App and a Token bound to the one entity the user consented to. The MCP client stores that token and calls the API as that App.
Users never see the words "Connector" or "App" — the Portal shows your product's own name and logo, and files the connection under Connected by you or Member-connected tools depending on who owns it (term reference).
Each user's authorization produces its own App on its own entity, so an MCP client only ever reaches the accounts a given user consented to — never "all accounts." Isolation is structural, the same as any Connector.
A plain connection only sees what was directly granted to the App. For an AI
assistant working with a user, request delegated access
too — add the literal token delegate to your scope (e.g. scope=viewer delegate). If the user picks it on the consent screen, your client sees what
they see within the consented scope, while its actions stay bounded by the
granted roles — and the user can revoke everything with one click in
Connections. This is the preferred pattern for agents — never ask a user to
paste a personal access token into a hosted
service; that hands over their full identity with nothing to constrain it.
Delegate mode must be enabled on your connector at registration (below).
To the user, this is not a checkbox called "delegation" — it is the option "My own tool — seeing my view", and afterwards their connection simply reads "Sees Klart as you do." Use those words when you explain the permission you are asking for (term reference).
What an MCP client needs
-
Discovery — a client that knows only the API host can find everything else from it:
GET https://api.klart.com/.well-known/oauth-protected-resourceGET https://api.klart.com/.well-known/oauth-authorization-serverThe first (RFC 9728) names the authorization server — Klart is its own. The second (RFC 8414) advertises the
authorization_endpoint(/oauth/v1/authorize), thetoken_endpoint(/oauth/v1/token), and the supported PKCE methods. A client does not even need to know these paths: any v1 request without a token returns401withWWW-Authenticate: Bearer resource_metadata="https://api.klart.com/.well-known/oauth-protected-resource", and the same links inerror.details.GET https://api.klart.com/links them too.An AI agent without MCP support can read
https://api.klart.com/llms.txtinstead: a plain-text, step-by-step quick start with that environment's host already filled in. Every environment serves its own. -
PKCE — Klart requires
code_challenge/code_verifier(S256). This is mandatory for MCP clients; there is no implicit or password grant. -
A registered connector — see below.
Registering your MCP connector
Local clients: no registration needed
If your MCP client runs on the user's own machine (a desktop assistant, a CLI agent), use the shared public connector — there is nothing to register:
| Client ID | ctr_local_ai_assistant |
| Redirect URI | http://127.0.0.1:<any port>/callback or http://localhost:<any port>/callback |
| Client type | Public — no secret; PKCE (S256) required |
| Delegate mode | Enabled — request scope=viewer delegate |
| Role ceiling | viewer (read-only) |
Loopback redirect URIs are matched port-agnostically (RFC 8252): bind any
free port at runtime and use it in your redirect_uri — the host and the
/callback path must match exactly, only the port is free. This is safe
because the client is public and PKCE binds each authorization code to the
process that started the flow; a shared client_id carries no secret and
grants nothing by itself — every access still requires the user's consent.
The shared connector is deliberately capped at the read-only viewer role.
Combined with delegated access (opt-in on the consent
screen), that is the right shape for an assistant working with a user: it
reads what the user sees, and nothing more.
Claude Code
Klart recognises Claude Code by its published client ID, so there is nothing to register and no client ID to type:
claude mcp add --transport http klart https://mcp.klart.com
Then run /mcp in a Claude Code session, or claude mcp login klart in a
shell, to sign in. Klart opens in your browser: pick what Claude Code may read
and approve. Claude Code acts as you, read-only, and you can withdraw it at
any time under Connections.
Claude Code versions before 2.1.80 cannot identify themselves this way. On
those, update Claude Code (claude update), or use the shared local connector
above:
claude mcp add-json klart '{"type":"http","url":"https://mcp.klart.com","oauth":{"clientId":"ctr_local_ai_assistant","scopes":"viewer delegate"}}'
Hosted services: administrative registration
A hosted MCP service has its own https redirect URI, which cannot ride the
shared connector — it needs its own registration. MCP dynamic client
registration (RFC 7591 — where a client self-registers automatically) is
not yet supported, so registration is administrative: contact Klart to
register your connector. You'll provide:
- a name and branding (shown on the consent screen),
- the redirect URI(s) your MCP client uses (matched exactly;
httploopback URIs are matched with any port per RFC 8252), and - whether you'll authenticate with a
client_secretor PKCE only (public clients use PKCE only).
You'll receive a client_id (and a client_secret if applicable).
The flow, briefly
- Discover the endpoints (
.well-knownabove). - Send the user to
GET /oauth/v1/authorizewith yourclient_id,redirect_uri,scope, and a PKCEcode_challenge. - The user logs in, chooses what kind of connection this is (an organization integration, their own tool, or their own tool seeing their view), and approves — for a specific scope.
- Exchange the returned
code(+code_verifier) atPOST /oauth/v1/tokenfor a bearer token. The response also carries arefresh_token; MCP clients that implement OAuth 2.1 refresh it automatically, so the connection keeps working after the one-hour access token expires (see Keeping access alive). - Call the API as that scoped App, sending the App's
scopeIdinX-Scope.
See Connectors & OAuth for the full request/response detail of each step.
Where to go next
- Connectors & OAuth — the complete authorization-code + PKCE flow.
- Delegated Access — seeing what the user sees, with their consent.
- Apps & API Keys — what an "App" is, and first-party access.
- Access Concepts & Portal Terms — what your users call all of this.
- API Reference → OAuth & Connectors.