@getholdings/mcp

@getholdings/mcp

Run your Holdings Workspace (invoices, quotes, clients, payments) from any MCP host — Claude, ChatGPT, Cursor, and others — in natural language, with every write previewed and confirmed.

Fastest way to connect: hosted URL (no install)

Holdings runs a hosted MCP server. Generate a key in Holdings → Settings → MCP, then paste your connection URL into your MCP client's custom-connector field:

https://mcp.getholdings.com/mcp?mcpKey=YOUR_MCP_KEY

That's it — no download, no local config. The key in the URL authenticates you and scopes the server to your company. Clients that accept a header can instead send Authorization: Bearer YOUR_MCP_KEY to the same URL. If a key leaks, regenerate it in Settings → MCP (the old key + URL stop working immediately).

The ?mcpKey= URL form is a secret in a URL — treat the URL like a password, and use the header form when your client supports it.

Local option: stdio (npm)

Holdings Workspace MCP server (stdio). Lets an MCP host — Claude Desktop, Cursor, and others — run your Holdings Workspace (invoices, quotes, clients, payments) in natural language, with every write previewed and confirmed.

How it works

Thin stdio MCP server (@modelcontextprotocol/sdk, StdioServerTransport). Every tool is an HTTPS call to the live Holdings v1 API with your company key. The guided-write intelligence — slot-filling, preview, the server-enforced confirmation gate, and humanized copy — lives server-side in the agent-actions layer, so this package stays thin and never drifts from the API.

Tools (Option C)

• Reads (one-shot): list_invoices, get_invoice, list_quotes, get_quote, list_clients, get_client, list_payments, get_company, capabilities, overview.
• Guided writes (three meta-tools): resolve_action → prepare_action (returns a preview + confirmationToken) → execute_action (runs it with the token, after you approve). A write cannot execute without a valid, payload-bound token — the server enforces this, not the model.

Install & configure

npm install -g @getholdings/mcp   # or run via npx

Add to your MCP host config (Claude Desktop example, claude_desktop_config.json):

{
  "mcpServers": {
    "holdings": {
      "command": "npx",
      "args": ["-y", "@getholdings/mcp"],
      "env": {
        "HOLDINGS_API_KEY": "hw_live_…",
        "HOLDINGS_API_BASE": "https://workspace.getholdings.com/api/v1"
      }
    }
  }
}

• HOLDINGS_API_KEY (required): your company API key. It scopes what the server can do.
• HOLDINGS_API_BASE (optional): defaults to production. Point it at a preview deployment for testing.

Build (from source)

cd packages/mcp
npm install
npm run build
npm start   # needs HOLDINGS_API_KEY in env

Safety

Writes go through the server confirmation gate (/agent/execute returns 428 for a write with no valid confirmationToken). Even a misbehaving host cannot push a write through without the user-approved, payload-bound token.