@getholdings/mcp

@getholdings/mcp

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.
• 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.