Verdly runs a remote Model Context Protocol (MCP) server, so you can let an AI assistant such as Claude or Cursor read your Verdly data and answer questions about your finances. This guide walks you through generating a key, connecting a client, and keeping things safe.

Before you start

You will also need an MCP-capable client, such as Claude Desktop, Cursor, or the MCP Inspector. The server is read-only: every tool reads your data, and none of them can change it.

Step 1 — Generate an API key

Your assistant authenticates as you using a Verdly API key. To create one, open Settings → API keys in the Verdly app and:

Give the key a recognisable name (for example, “Claude MCP”) so you can tell your keys apart later.
Choose what the key can access — a key only ever has the access you grant it. The MCP tools read your financial data and can’t change your holdings, snapshots or other records, so keep Financial data selected.
Choose when it should expire. We recommend the shortest period that suits you.
Select Create new key. The full key is shown once — copy it straightaway and store it somewhere safe, because it cannot be shown again.

A Verdly key always starts with vk_. If you lose it, simply revoke it and create a new one.

Step 2 — Connect Verdly to your client

The server speaks the MCP Streamable HTTP transport at https://mcp.verdly.io/ and authenticates with your key in the Authorization header as Bearer vk_….

Claude Desktop

Claude Desktop connects to remote servers through the mcp-remote bridge. Open Settings → Developer → Edit Config to open claude_desktop_config.json, add the block below, then restart Claude Desktop. Replace vk_your_key_here with the key you generated.

{
  "mcpServers": {
    "verdly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.verdly.io/",
        "--header",
        "Authorization: Bearer vk_your_key_here"
      ]
    }
  }
}

Cursor

Cursor connects to remote servers directly. Create or edit .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json) and add:

{
  "mcpServers": {
    "verdly": {
      "url": "https://mcp.verdly.io/",
      "headers": {
        "Authorization": "Bearer vk_your_key_here"
      }
    }
  }
}

Cursor expands ${env:NAME} inside headers, so you can keep the key out of the file by writing "Authorization": "Bearer ${env:VERDLY_API_KEY}" and setting VERDLY_API_KEY in your environment instead.

VS Code (GitHub Copilot)

Add an HTTP server to .vscode/mcp.json in your workspace. The inputs block prompts you for the key the first time the server starts and keeps it out of the file:

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

ChatGPT

Other clients

Any client that supports a remote Streamable HTTP MCP server with a custom header works the same way: set the server URL to https://mcp.verdly.io/ and send the header Authorization: Bearer vk_…. For a client that can only run local (stdio) servers, use the mcp-remote bridge shown under Claude Desktop above. Field names vary — check your client’s documentation for where to add a remote MCP server and a custom header.

Available tools

Once connected, your assistant can call any of these read-only tools. Amounts always carry their currency, so figures are never ambiguous.

list_holdings — your assets and debts, each with the currency its values are recorded in.
list_categories — the categories you have organised your holdings into.
get_net_worth — your current net worth and full history in your base currency; accepts an optional date range.
list_snapshots — the values you recorded for a given month, one row per holding.
get_milestones — your milestones with their current progress towards each target.
get_insights — your latest AI-generated insights summary, if you have generated one.
get_performance — year-by-year performance of your net worth against UK CPI inflation.
get_activity — your recording activity: most recent period, current streak, and periods with data.

Rate limits

Requests are rate limited to keep the service responsive for everyone. If you go over a limit, calls are briefly refused with a “Too many requests” error and recover on their own — your assistant can simply try again in a moment.

Per key: bursts of up to 60 requests, replenishing at roughly 1 request per second.
Per account: bursts of up to 90 requests across all your keys combined, replenishing at roughly 3 requests per second.

Keeping your key safe

Store it in a password manager. Never commit it to source control or paste it into a shared chat.
Use a separate key for each tool or device, so you can revoke one without disrupting the others.
Set an expiry, and revoke any key you no longer use.

Revoking a key

To stop a key working, open Settings → API keys, find the key, and select Revoke. Revocation takes effect immediately: any assistant using that key loses access at once. This cannot be undone, so if you still need access, create a fresh key first.