dimesumdevelopers API reference Console Open the app

MCP server

Ask an assistant "who owes me the most right now?" or tell it "add ₹1,200 dinner to Goa trip, split with Ravi and Priya, I paid", and it does it with your key, under your rules.

What MCP is#

The Model Context Protocol is an open standard that lets an AI assistant call tools on a server. Dimesum's MCP server gives an assistant 14 tools for your groups, bills and balances; each tool is a call to the same REST API with your key, so every permission check, scope and rate limit applies exactly as it does to your own scripts.

The endpoint#

URLhttps://api.dimesum.com/mcp (local: http://localhost:8080/mcp)
TransportStreamable HTTP: POST JSON-RPC 2.0, JSON responses (no server-sent event stream)
Protocol versions2025-06-18 (current); 2025-03-26 and 2024-11-05 are also accepted
AuthenticationAuthorization: Bearer dms_live_…, a developer key
SessionsNone: the server is stateless and issues no Mcp-Session-Id
Methodsinitialize, ping, tools/list, tools/call

A read-only key is enough for every read tool. The write tools (add_expense, add_comment, record_payment) need a read and write key; with a read-only key they return a tool error naming api_key_read_only. Start read-only, and widen it when you trust the setup.

Claude Code#

Shell
export DIMESUM_API_KEY="dms_live_..."
claude mcp add --transport http dimesum https://api.dimesum.com/mcp --header "Authorization: Bearer $DIMESUM_API_KEY"

Your shell expands $DIMESUM_API_KEY when you run the command, so the key is written into Claude Code's MCP configuration for this project. Add --scope user to use it in every project. Check it with claude mcp list, then ask in a session: "list my Dimesum groups".

Claude Desktop#

Claude Desktop starts local servers, so it reaches a remote one through the mcp-remote bridge (needs Node.js). Open Settings › Developer › Edit Config and add this to claude_desktop_config.json:

JSON
{
  "mcpServers": {
    "dimesum": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.dimesum.com/mcp",
        "--header",
        "Authorization:Bearer ${DIMESUM_API_KEY}"
      ],
      "env": {
        "DIMESUM_API_KEY": "dms_live_..."
      }
    }
  }
}

The header is written without a space after the colon on purpose: some clients split arguments on spaces, and mcp-remote accepts it either way. Restart Claude Desktop; the tools appear under the tools menu in a new chat.

Cursor#

Cursor speaks Streamable HTTP directly. In ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

JSON
{
  "mcpServers": {
    "dimesum": {
      "url": "https://api.dimesum.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DIMESUM_API_KEY}"
      }
    }
  }
}

${env:DIMESUM_API_KEY} reads the key from the environment Cursor was started in. If your version does not expand it, put the key in directly, and keep that file out of git.

VS Code#

With GitHub Copilot's agent mode, add .vscode/mcp.json. The inputs block makes VS Code ask for the key once and keep it in its secret storage rather than in the file:

JSON
{
  "inputs": [
    { "type": "promptString", "id": "dimesum-key", "description": "Dimesum API key", "password": true }
  ],
  "servers": {
    "dimesum": {
      "type": "http",
      "url": "https://api.dimesum.com/mcp",
      "headers": { "Authorization": "Bearer ${input:dimesum-key}" }
    }
  }
}

Other clients#

Any MCP client that supports the Streamable HTTP transport with custom headers works: point it at the URL and send the Authorization header. Clients that only start local servers can use the same mcp-remote bridge as Claude Desktop.

Tools#

Money in tool arguments is a decimal string in the currency's major unit ("450", "12.50"), because that is how people and models say it; the server converts it with the currency's exponent and refuses more decimals than the currency has (yen has none). Everything a tool returns is the REST API's own JSON, in minor units.

Writes accept an optional idempotency_key: any string unique to the action. Repeating a call with the same key replays the first result instead of writing twice, which matters when an assistant retries.

ToolWhat it doesArgumentsREST calls it makes
whoami
Who am I
read
The account this key belongs to: name, email, home currency and time zone.noneGET /v1/me
list_groups
List groups
read
Every group you are in, with your balance in each (a positive net means the group owes you).noneGET /v1/groups
get_group
Get a group
read
A group's members (with member ids, needed to name who paid or who shares a bill), its currency and settings.
  • group_id string required
    The group's id, from list_groups.
GET /v1/groups/{groupID}
list_expenses
List bills
read
A group's bills, newest first, one page at a time.
  • group_id string required
    The group's id.
  • limit integer
    How many, 20 by default (1 to 100).
  • cursor string
    next_cursor from the previous page.
GET /v1/groups/{groupID}/expenses
get_expense
Get a bill
read
One bill with its splits, payers, version and comments count.
  • group_id string required
    The group's id.
  • expense_id string required
    The bill's id.
GET /v1/groups/{groupID}/expenses/{expenseID}
add_expense
Add a bill
write
Adds a bill to a group, split equally among the people named (everyone by default), paid by one member (you by default), or by item with its tax, tip, fees and discounts. Returns the bill.
  • group_id string required
    The group's id.
  • description string required
    What it was, up to 120 characters.
  • amount string
    A decimal in the currency's major unit, e.g. "450" or "12.50". No more decimals than the currency has (JPY has none). Required unless the bill is by item.
  • currency string
    ISO 4217 code; the group's currency when left out.
  • paid_by_member_id string
    Who paid, as a member id from get_group; you when left out.
  • participant_member_ids array of string
    Who shares it, as member ids; everyone in the group when left out.
  • occurred_on string
    The bill's date, YYYY-MM-DD; today in your time zone when left out.
  • shares object
    Optional, for an uneven split: member id to decimal amount, summing exactly to amount. Replaces participant_member_ids.
  • items array of object
    Optional, for a bill by item: { description, amount, member_ids } per line; member_ids left out means everyone in the bill shared it. The total is the lines plus the extras, so amount may be left out; if sent, it must agree.
  • extras array of object
    Optional, with items: { kind, label, amount or percent } in the order the bill prints them. kind is TAX, TIP, FEE or DISCOUNT. A percent is worked out on the items plus every extra above it, except a tip.
  • idempotency_key string
    Optional. Any string unique to this action; repeating a call with the same key replays it instead of writing twice.
GET /v1/groups/{groupID}
POST /v1/groups/{groupID}/expenses
create_group
Create a group
write
Creates a group you own, for moving a history in from a spreadsheet or another app. Returns it with your member id.
  • name string required
    The group's name, up to 60 characters.
  • idempotency_key string
    Optional. Any string unique to this action; repeating a call with the same key replays it instead of writing twice.
POST /v1/groups
add_member
Add a person
write
Adds somebody to a group by name, as a kept place they can claim later. Use it for a person in your history who is not in the group yet.
  • group_id string required
    The group's id.
  • name string required
    Their name as it should appear.
  • idempotency_key string
    Optional. Any string unique to this action; repeating a call with the same key replays it instead of writing twice.
POST /v1/groups/{groupID}/members
add_comment
Comment on a bill
write
Adds a comment to a bill's thread.
  • group_id string required
    The group's id.
  • expense_id string required
    The bill's id.
  • text string required
    The comment, up to 1,000 characters.
  • idempotency_key string
    Optional. Any string unique to this action; repeating a call with the same key replays it instead of writing twice.
POST /v1/groups/{groupID}/expenses/{expenseID}/comments
get_balances
Group balances
read
Everyone's balance in one group, per currency. Positive: the group owes them; negative: they owe the group.
  • group_id string required
    The group's id.
GET /v1/groups/{groupID}/balances
get_my_balances
My balances everywhere
read
Who owes you and whom you owe, across every group, per currency.noneGET /v1/me/balances
record_payment
Record a payment
write
Records that you paid somebody in a group (the money moved in your own bank or app; Dimesum never moves it). The other person confirms it.
  • group_id string required
    The group's id.
  • to_member_id string required
    Who you paid, as a member id.
  • amount string required
    A decimal in the currency's major unit, e.g. "450" or "12.50". No more decimals than the currency has (JPY has none).
  • currency string
    ISO 4217 code; the group's currency when left out.
  • method string
    How you paid: UPI, CASH, OTHER, PAYPAL, VENMO, CASHAPP, WISE, REVOLUT, ZELLE, PAYNOW, PIX, IBAN or BANK.
  • reference string
    The payment app's reference, if any.
  • idempotency_key string
    Optional. Any string unique to this action; repeating a call with the same key replays it instead of writing twice.
GET /v1/groups/{groupID}
POST /v1/groups/{groupID}/settlements
get_insights
Spending insights
read
Your share of spending across groups for a month: totals by group, by day and the year around it.
  • month string
    YYYY-MM; this month when left out.
GET /v1/me/insights
list_people
People
read
People you keep in Dimesum (added by their code or number).noneGET /v1/people

People are named by member id, which an assistant gets from get_group. The server's initialize answer tells the model this, so a well-behaved assistant looks the group up first.

Example prompts#

You sayWhat the assistant does
"Add ₹1,200 dinner to Goa trip, split with Ravi and Priya, I paid"list_groups to find Goa trip, get_group for the member ids, then add_expense with amount: "1200" and Ravi, Priya and you as participants.
"Split this receipt: I had the thali, Ravi the paneer, the lassi was shared, plus 10% service and 5% GST"get_group for the member ids, then add_expense with items (each line and who had it) and extras (FEE 10 percent, then TAX 5 percent). The total is worked out for you, GST included on the service charge.
"Who owes me the most right now?"get_my_balances, then compares per currency (it should not add rupees to yen).
"Record that I paid Asha ₹500 by UPI, ref 628104551923"list_groups and get_group to find Asha's member id, then record_payment with method: "UPI" and the reference. Asha confirms it in her app.
"What did I spend on shared stuff in August?"get_insights with month: "2026-08".
"What was the last thing added to the flat group?"list_groups, then list_expenses for that group.
"Tell Ravi on the cab bill that I paid the toll too"list_expenses to find the bill, then add_comment.

Good habits for an assistant with write access

Ask it to repeat back the group, amount and people before it adds anything. Dimesum never moves money, and bills can be deleted, but the people in your group see a bill as soon as it is added.

Raw JSON-RPC with curl#

What a client does under the hood, if you are building one or want to test by hand.

1. Initialize

curl
curl https://api.dimesum.com/mcp \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Mcp-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "dimesum", "title": "Dimesum", "version": "…" },
    "instructions": "Dimesum keeps shared expenses between people in groups. Amounts are decimals in the currency's major unit (\"12.50\"). …"
  }
}

A notification (a request without an id, such as notifications/initialized) gets 202 Accepted and no body.

2. List the tools

curl
curl https://api.dimesum.com/mcp \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Each tool comes with its inputSchema (JSON Schema) and annotations (readOnlyHint, idempotentHint).

3. Call a tool

curl
curl https://api.dimesum.com/mcp \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "add_expense",
      "arguments": {
        "group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
        "description": "Lunch",
        "amount": "450",
        "idempotency_key": "lunch-2026-09-28"
      }
    }
  }'

The result carries the API's JSON twice: as text for the model, and as structuredContent for clients that read it.

Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\"id\":\"…\",\"description\":\"Lunch\",\"amount_minor\":45000,…}" }],
    "isError": false,
    "structuredContent": { "id": "…", "description": "Lunch", "amount_minor": 45000, "currency": "INR" }
  }
}

When the API refuses, the result has isError: true and the text is the status and error envelope, for example HTTP 403: {"error":{"code":"not_editor",…}}. A malformed request is a JSON-RPC error instead: -32700 (not JSON-RPC 2.0), -32601 (unknown method) or -32602 (tools/call without a name).

The console has an MCP tester that sends these three calls from your browser.