Skip to main content

Clatri MCP

The Clatri MCP lets you connect your Clatri information to external AI clients like Claude Desktop, Cursor, Claude Code, or Codex. The external assistant reads and, if you authorize it, writes to your data — always within the permissions you grant to the token.

For the curious: MCP stands for Model Context Protocol, an open standard created by Anthropic. Any compatible client can connect to Clatri without us having to build a proprietary integration.

When to use the MCP?

If you already talk to Claude or Cursor all day and would like them to have access to your Clatri data without opening the app. For example: "how much did I spend on restaurants this month?" directly in Claude Desktop, no copy-paste.

How it works, in one picture​

Every time the AI client asks a question, it sends the token to the Clatri backend. The backend validates the token, checks which entities and permissions it has, runs the requested tool, and returns the response. It never exposes your password, your app session, or impersonates you outside Clatri.

Requirements​

You need an active Clatri subscription

The MCP is a premium feature. Without a subscription:

  • You can't create tokens — the button returns an error asking you to renew.
  • If your subscription expires with active tokens, those tokens stop working (they respond 402) until you reactivate. They're not deleted — they go back to working automatically when you renew.

This covers the cost of processing your requests with low latency and keeping the infrastructure secure.

You need an MCP-compatible client

The most popular ones:

  • Claude Desktop (Mac, Windows) — graphical install
  • Claude Code (CLI) — claude mcp add
  • Cursor (IDE) — Settings → MCP
  • Codex CLI (OpenAI) — ~/.codex/config.toml

Other clients that also work: Continue, Cline, Zed, mcp-cli, any integration that speaks streamable HTTP MCP.

Step 1 — Create your token​

  1. Open the Clatri app → Settings → API tokens.
  2. Tap + New token.
  3. Give it a name you'll recognize (e.g. "Claude Desktop on my Mac").
  4. Choose the permission level:
    • Read only — the client can query but doesn't modify anything.
    • Read + Write — can create and edit (expenses, episodes, notes, etc.).
    • Full access — also includes delete.
  5. Tap Create token.
Copy it right away

The token is shown only once. If you lose it, we can't recover it — you have to revoke it and create a new one. Paste it immediately into your client or save it in your password manager.

The token expires automatically after 6 months. You can revoke it manually anytime from the same screen.

Step 2 — Connect it to your client​

From the terminal:

claude mcp add clatri \
  --transport http \
  --scope user \
  https://api.clatri.com/mcp \
  --header "Authorization: Bearer clt_mcp_YOUR_TOKEN_HERE"
  • --scope user registers it globally (available in every project). Use --scope project if you only want it in this repo (lives in .mcp.json).
  • --transport http is required because the Clatri MCP is remote.

Verify it connected:

claude mcp list

You should see clatri: connected ✓. In your next Claude Code session, the whoami, list_entities and other tools will appear automatically.

Step 3 — Check that it works​

In your freshly configured client, type one of these:

Who am I in Clatri and which entities do I have access to?
List my Clatri entities.

If everything is OK, the client will use the whoami and list_entities tools and reply with your name, the available entities (Personal, Company, etc.) and the token's permissions.

What you can ask it (examples)​

Once connected, these prompts work in any client:

QuestionTools it uses
"How much did I spend on restaurants last month from my personal account?"list_entities, read_income_statement
"Summarize my accounts and current balances."list_entities, list_accounts, get_balance
"Log a $45 USD Uber expense for today on Gurwi LLC."list_entities, create_expense (requires write scope)
"When is my next obligation due and how much is it?"list_obligations
"What medications am I currently taking."list_medications
For vague questions

If you don't know exactly which tool to use, just ask the client in natural language. Modern LLMs pick the right tools automatically.

Security​

The token never grants access outside Clatri

Even if the token leaks:

  • It only applies the scopes you granted (read / write / delete).
  • It only reaches data inside Clatri — no access to your password, no email change, no 2FA reset.
  • It can't create more tokens, revoke others, or touch your subscription.
  • You can revoke it instantly from Settings → API tokens.

Every operation is logged in the audit log (Settings → API tokens → tap a token → view recent activity). If you see unusual usage, revoke it.

Restrict a token to specific entities

By default a token has access to the same entities as your account — own and shared. When you create or edit a token you can select only the entities the AI client will see. Useful for:

  • A token for your accountant that only sees the company.
  • A test token that only accesses a sandbox entity.
  • An AI client on your personal computer that can't touch work data.

After creation you can change entities, permissions, and the name from Settings → API tokens → tap the menu (···) → Edit. You don't have to generate a new token every time you tweak its scope.

The token expires after 6 months

For security. When it expires, you simply create a new one and replace it in the client. There's no way to extend the expiration — that's by design.

Troubleshooting​

The client says "401 unauthorized"
  • The token expired → create a new one.
  • You revoked it by mistake → create a new one.
  • You copied it wrong (missing the clt_mcp_ prefix or with an extra space) → verify the Authorization: Bearer clt_mcp_... header.
The client says "402 subscription_inactive"

Your Clatri subscription isn't active. Renew it in the app and try again — the same token keeps working.

The client says "403 scope_denied" or "entity_denied"
  • scope_denied: the token doesn't have the required permission (e.g. it wants to write but you only gave it read). Create a new token with more scopes and replace.
  • entity_denied: the client tried to touch an entity the token doesn't allow. If you want to broaden it, revoke and create a new token without entity restriction.
"Browser origins not allowed"

You're trying to talk to /mcp from a browser or web tab. Legitimate MCP clients are native processes (Claude Desktop, Claude Code CLI, Cursor desktop). This is anti DNS-rebinding protection — it's not a bug, it's by design.

The client doesn't detect the tools after installing
  • Fully restart the client (not just minimize).
  • Claude Code: run claude mcp list to see if it appears. If it says "failed", check the header format.
  • Codex: run with --verbose or check logs in ~/.codex/log/.

Frequently asked questions​

How many tokens can I create?

Up to 10 active tokens per user. If you reach the limit, revoke an old one before creating a new one.

Can I share a token with someone else?

Technically yes (it's just a string), but not recommended. If that person needs access to your Clatri, it's better to share the entity from Settings → Share entities and give them their own access with their account. Tokens are personal.

Do AI-client actions show up in my Clatri chat history?

After a task that changes data, the external agent is instructed to call registrar_resumen_actividad. This saves one External activity · MCP card in the entity chat, with a summary, expandable changes and local time. Read-only tasks do not create a card. Delivery depends on the client following the instruction; it is not an automatic session detector or a push notification. The card is the external agent’s report, not independent verification by Clatri.

What happens to my token when I rotate my Supabase API keys or JWT signing keys?

Nothing. The MCP token is independent from Supabase's internal auth system. Backend key rotations are transparent to MCP tokens.

Are there rate limits?

Yes, but conservative — designed for normal human usage via an AI client, not for mass automation. If you hit the limit, you'll see 429 rate_limited in the audit log. If you need more volume, contact us.

Personal context through MCP​

read_user_context returns the active entity’s description, behavioral defaults, personality and preferences shared across channels. The client is instructed to read it at the start of a task; MCP does not automatically inject it into every external conversation. buscar_memoria retrieves relevant historical memories.

edit_entity_context and remember_user_preference can use an exact user quote from the external conversation when source_message_id is omitted. That evidence is labeled client-reported, not verified Clatri chat history. Chat-only preferences remain excluded from external context; use channel_scope=all only when the user authorizes sharing across channels.

Reconnect the MCP after updates so the client refreshes tools and instructions. Existing tokens remain valid within their permissions. The documentation link remains available after creating tokens in Flutter and web.

Totals and usage when querying from Claude​

For “How much did I spend or earn this month/year?”, request the income statement (read_income_statement). It uses the same accounting basis as Earned and spent: transfers between your own accounts and debt principal payments are not income or expenses. Use read_cashflow_report for money entering or leaving accounts.

read_expenses and read_incomes show movement details and a separate accounting total. The detail list can be limited; do not sum it to calculate the period total.

Example: “Use Clatri MCP to read my income statement from September 1 through September 30, 2026. Report income, expenses, and the tool used.”

These direct data queries do not run Clatri's conversational model. Adding “without spending Clatri tokens” does not change billing. Claude has its own usage, and MCP access requires an active Clatri subscription.

“Server disconnected” on Windows​

  1. Check node --version, npm --version, and where npx.cmd in cmd.
  2. Use npx.cmd and the environment-variable configuration above. If the executable cannot be found, use the full path returned by where, escaping backslashes as \\ in JSON.
  3. Fully quit and reopen Claude.
  4. If it still fails, open Developer → clatri → View logs. “Server disconnected” alone cannot distinguish installation, authentication, and network errors. Hide tokens before sharing logs or screenshots; revoke and replace any exposed token.