MCP access

Connect your ledger to an external AI client: create a token, choose its permissions and copy the client configuration.

Calends has a built-in MCP server. Once connected, AI assistants such as Claude Code, Codex and Cursor can query and update your ledger directly: “What renews next week?” “Netflix went up to $17.99 from today.”

Endpoint

https://calends.example.com/mcp

• Transport: stateless Streamable HTTP. Each POST carries one JSON-RPC request (or a batch) and gets JSON back; there’s no SSE stream and no session.
• Auth: the header Authorization: Bearer <token>.
• Supported protocol versions: 2025-06-18, 2025-03-26, 2024-11-05.

Create a token

1. Open AI access in the sidebar and click New token.
2. Give it a name (which AI it’s for) and choose its scope:
   • Read & write: can query, and also add and change subscriptions, charges and payments;
   • Read-only: can only query, and can’t change anything.
3. Click Create. The token starts with sub_ and is only returned when created. The current page keeps it temporarily for snippets; after a refresh it cannot be retrieved. If lost, use Revoke and create another.

Use a separate token for each assistant so you can revoke them individually. The token list shows name, scope, the first few characters, when it was created and when it was last used. The server only stores a SHA-256 hash of each token.

With a read-only token, tools/list only shows read tools, and calling a write tool returns an error.

Configure your client

The AI access page provides eight setup options. A freshly created token is included in the current page’s snippets; it cannot be retrieved after a refresh. Use Copy config only, or send the generated prompt to the relevant assistant. Copied content may contain the token.

Claude Code

Run this in your terminal, replacing <token> with the token you just created:

claude mcp add --transport http calends https://calends.example.com/mcp \
  --header "Authorization: Bearer <token>"

Codex

Set the token environment variable in your terminal, then register the server. The process starting Codex must also have access to this variable.

export CALENDS_TOKEN='<token>'
codex mcp add calends --url https://calends.example.com/mcp --bearer-token-env-var CALENDS_TOKEN

Cursor

Merge this into ~/.cursor/mcp.json. Right after creating a token, AI access also offers Add to Cursor.

{
  "mcpServers": {
    "calends": {
      "url": "https://calends.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Claude Desktop

Merge this into claude_desktop_config.json to connect through mcp-remote. Your computer must be able to run npx.

{
  "mcpServers": {
    "calends": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://calends.example.com/mcp", "--header", "Authorization: Bearer <token>"]
    }
  }
}

Gemini CLI

Run this in your terminal:

gemini mcp add --transport http calends https://calends.example.com/mcp \
  --header "Authorization: Bearer <token>"

Grok Bot

1. In Grok Bot, open Settings → Plugins and add an MCP server.

2. Enter the name, URL and header below:

   name: calends
   url: https://calends.example.com/mcp
   headers:
     Authorization: Bearer <token>

3. Save it and ask Grok Bot to list your active subscriptions.

Caution

Grok Bot connects from the cloud, so your ledger must have a publicly reachable URL. It cannot reach localhost or a private network address.

DeepSeek Harness

This setup is marked Experimental. Merge the following into ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: mcp-calends
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: calends
        transport: streamable-http
        url: https://calends.example.com/mcp
        headers:
          Authorization: 'Bearer <token>'

This is an external MCP client, configured separately from Calends’ built-in DeepSeek assistant.

HTTP

This option is labeled Other in the interface. Any MCP client that supports Streamable HTTP can connect. Start by requesting the tool list:

POST https://calends.example.com/mcp
Authorization: Bearer <token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Once connected, ask the assistant to call get_overview and check today’s date, base currency and active subscription count. These snippets match those generated by Calends’ AI access page; after client upgrades, check which format the client accepts.

Preview before writing

Every write tool supports dry_run: pass true to get a preview without saving. MCP does not enforce a draft-confirmation step: a read-write token applies changes directly when dry_run is omitted or false. For irreversible operations such as deleting a subscription, the tool description tells the assistant to preview first and let you confirm.

Each tool carries MCP annotations — read tools are marked read-only, delete tools destructive — so clients that support them can decide when to ask you.

The full list is in the MCP tool reference.

Global switch

Settings → Sharing & access → AI access (MCP), or the toggle at the top of the AI access page. When it’s off:

• /mcp rejects every request (HTTP 403), so all issued tokens stop working for now;
• AI access disappears from the sidebar.

Turn it back on and the existing tokens work again. This switch doesn’t affect the built-in assistant.

Note

Text returned over MCP uses the language from Settings → General → Language; with System default, the language the app was last used in. Instances in demo mode don’t accept MCP requests.