Using the MCP server

Connect Claude Desktop or Claude Code to your Income Graph Cloud graphs.

The Income Graph MCP server lets an AI assistant read your cloud graphs and run the calculator, and, with a read-write key, create, edit and delete graphs. It is a thin wrapper over the public API: it has no database access of its own, and every tool call is an API request made with your key, so the same subscription check, rate limits and errors apply.


URL	`https://mcp.incomegraph.net/mcp`
Status	Generally available
Transport	Streamable HTTP (stateless, JSON responses)
Authentication	`Authorization: Bearer <your API key>`

The server used to be reached at https://api.incomegraph.net/mcp. That address keeps working, so existing configurations need no change.

Create a key first. Use one key per client so you can revoke it independently. Choose Read only if the assistant should just look at your graphs, and Read and write only if you want it to change them.

Claude Code

claude mcp add --transport http incomegraph https://mcp.incomegraph.net/mcp \
  --header "Authorization: Bearer $INCOMEGRAPH_API_KEY"

Then ask: “List my Income Graph graphs and summarize the first one.”

Claude Desktop

Claude Desktop starts local servers, so bridge to the remote URL with mcp-remote. Open Settings, Developer, Edit Config and add:

{
  "mcpServers": {
    "incomegraph": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.incomegraph.net/mcp",
        "--header", "Authorization:${INCOMEGRAPH_AUTH}"
      ],
      "env": { "INCOMEGRAPH_AUTH": "Bearer igk_paste_your_key_here" }
    }
  }
}

Restart Claude Desktop. The Authorization:${...} form (no space after the colon) avoids an argument-quoting bug in some Windows shells.

Tools

Each tool maps to one API operation, and its arguments are that operation’s parameters.

Tool	API call	Use it to
`get_account`	`GET /v1/me`	Check the key and see its limits.
`list_graphs`	`GET /v1/graphs`	Find graphs. Takes `limit` and `cursor`.
`get_graph`	`GET /v1/graphs/{graphId}`	Read one graph with all its sources.
`get_graph_summary`	`GET /v1/graphs/{graphId}/summary`	Get revenue, fees, profit, margin and goal progress.
`calculate`	`POST /v1/calculations`	Run what-if numbers without saving anything.
`create_graph`	`POST /v1/graphs`	Make a new graph, optionally with sources. Takes an optional `idempotencyKey`.
`update_graph`	`PATCH /v1/graphs/{graphId}`	Rename a graph, change its goals, or replace its sources.
`delete_graph`	`DELETE /v1/graphs/{graphId}`	Permanently delete a graph.

The first five tools only read and are annotated readOnlyHint: true. The last three need a read-write key; with a read-only key they return insufficient_scope and change nothing. create_graph is additive, update_graph and delete_graph are annotated destructiveHint: true, so clients can ask you before running them.

If the API refuses a call (for example subscription_required or rate_limited), the tool returns the API’s error JSON so the assistant can explain it.

Editing graphs with an assistant

Try: “Create an Income Graph called Consulting with one recurring income source of $100,000 a year.” The assistant builds a source list like this one:

[{ "id": "1", "type": "recurring", "name": "Consulting retainer", "amount": 100000, "units": 1, "period": "annual", "fees": [] }]

Source ids are numeric strings, revenue streams carry a period and a fees list, and a group lists its members’ ids in children while each member names the group in parentId. The tool descriptions teach assistants these rules, and a mistake comes back as an invalid_request with the exact location to fix.

Updates and deletes are guarded. The assistant reads the graph first and sends its updatedAt as expectedUpdatedAt; if you edited the graph in the app in the meantime, the call fails with conflict and the assistant must read again before retrying. The tool descriptions also tell assistants to confirm with you before deleting. A deleted graph disappears from the web app the next time it syncs (when you open the app or return to its tab). delete_graph returns the whole deleted graph, so a mistake can be undone by recreating it, though it gets a new id.

Troubleshooting

The client says 401 or “missing_api_key”: the Authorization header is not reaching the server. Re-check the header line in your config.
invalid_api_key: the key was revoked or mistyped. Create a new one.
subscription_required: the account behind the key has no active Income Graph Cloud plan.
insufficient_scope: the key is read-only. Create a read-write key on the account page and use that one for editing.
conflict: the graph changed since the assistant read it. Ask it to read the graph again and redo the change.
No graphs listed: only graphs synced to the cloud are visible. Open the app while signed in and they sync.