Connect your AI assistant to Spendrein

Quickstart

The fastest path from zero to a working chat-driven audit. Allow about five minutes end to end.

1. 1

   Issue a credential

   Open Settings and find AI assistant integration. Click Issue credentialand copy the value — it's shown once. Spendrein only stores a SHA-256 hash, so the cleartext can't be re-displayed later.

2. 2

   Add Spendrein to your assistant

   Add a new remote HTTP MCP server in your assistant's connector / MCP settings. Configuration is two values: an endpoint and a Bearer credential.

   MCP_ENDPOINT=https://spendrein.com/api/mcp
   MCP_AUTH_HEADER="Authorization: Bearer spr_mcp_REPLACE_WITH_YOUR_CREDENTIAL"

3. 3

   Verify the connection

   Send a JSON-RPC tools/list request — every MCP server must return its registered tools. A 200 response listing four tools means you're wired up.

   curl -s https://spendrein.com/api/mcp \
     -H "Authorization: Bearer $SPR_MCP_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/list"
     }' | jq '.result.tools[].name'
   
   # expected:
   # "audit.query"
   # "benchmark.lookup"
   # "subscription.cancel"
   # "subscription.negotiate"

4. 4

   Ask your assistant a question

   In your assistant chat, ask something only Spendrein could answer. The assistant will pick the right tool, request authorization, and call it.

Architecture

A request from your assistant takes a single hop to Spendrein. There's no proxy, no message broker, no background service — the assistant is the JSON-RPC client and /api/mcp is the JSON-RPC server.

┌────────────────┐    ┌──────────────────┐    ┌─────────────────────────┐
│ Your assistant │───▶│ Bearer-auth gate │───▶│ Tool dispatcher         │
│ (Claude / GPT  │    │ /api/mcp         │    │  • audit.query          │
│  Cursor / ...) │    │                  │    │  • benchmark.lookup     │
└────────────────┘    └──────────────────┘    │  • subscription.cancel* │
        ▲                     │               │  • subscription.negotiate*│
        │                     ▼               └────────────┬────────────┘
        │             ┌──────────────────┐                 │
        │             │ Rate limiter     │                 ▼
        │             │ (Upstash Redis)  │      ┌─────────────────────┐
        │             └──────────────────┘      │ Supabase Postgres    │
        │                                       │ (RLS-scoped query)   │
        │                                       └────────────┬────────┘
        │                                                    │
        │                                                    ▼
        │                                       ┌─────────────────────┐
        └───────────────────────────────────────│ Audit log           │
                                                │ (tool_call_events)   │
                                                └─────────────────────┘

* Paid-plan only

Authentication

The endpoint accepts exactly one authentication mechanism: a Bearer credential in the Authorization header. URL-parameter tokens are explicitly rejected to keep credentials out of access logs and browser history.

POST /api/mcp HTTP/1.1
Host: spendrein.com
Authorization: Bearer spr_mcp_4Bx9Lq7nJ8fKpMnVgT2sRxYz0WqEvN3uPAaBcDeFgHiJ
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

PrefixRequiredspr_mcp_

Reserved namespace. Lets GitHub secret scanners and other tooling identify a leaked credential without inspecting any account-bound state.

BodyRequired43 chars · base64url

256 bits of entropy from crypto.randomBytes(32). Treat the full string as a password equivalent — it can read your audit history and, on paid plans, trigger cancellations.

Header formRequiredAuthorization: Bearer …

RFC 6750. The Bearer keyword is case-insensitive; everything after the single space is the credential.

Tools

Spendrein exposes four tools. Two are read-only and available to every account; two are write actions reserved for paid plans. All inputs and outputs are validated against strict Zod schemas — extra properties are rejected.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "audit.query",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "benchmark.lookup",
    "arguments": { "vendor_name": "Notion" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "subscription.cancel",
    "arguments": {
      "subscription_id": "8d2e..."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "subscription.negotiate",
    "arguments": {
      "subscription_id": "8d2e...",
      "target_price": 12,
      "context_hint": "Team shrinking from 12 to 6 seats."
    }
  }
}

Client setup

Configuration snippets for the most common MCP clients. The values are universal: the endpoint is https://spendrein.com/api/mcp and the auth header is Authorization: Bearer spr_mcp_…. Everything else is client-specific JSON.

Server name:    Spendrein
URL:            https://spendrein.com/api/mcp
Auth:           Bearer token
Token:          spr_mcp_REPLACE_WITH_YOUR_CREDENTIAL

— No local install required. Spendrein runs as a remote server, not a
   local Claude Desktop / ChatGPT-Desktop process.

Example prompts

Three end-to-end conversations that exercise the toolset. Drop them into any connected assistant — the wording isn't load-bearing, but the verbs ("query", "benchmark", "cancel", "negotiate") help the assistant pick the right tool on the first try.

Security

Rate limits

Limits are enforced per credential, per tool class, on a rolling minute window via Upstash Redis. Rejected calls still decrement the budget — that closes the "trigger errors to starve the limiter" loophole.

Read tools60 / minute / credential

Applies to audit.query and benchmark.lookup. Generous enough for interactive chat; tight enough to block scrape loops.

Write tools10 / minute / credential

Applies to subscription.cancel and subscription.negotiate. Write actions can't reasonably need more — every one represents a real user decision.

Credential lifecycle5 / hour / account

Issuance + revocation actions on the credential itself. Stops accidental loops in Settings UIs from tripping the security mailer.

Error reference

Errors return JSON-RPC envelopes with a stable error discriminator and a human-readable message. Tool-specific extras (the candidates list on subscription_not_found_by_name, the retry_after_seconds field on rate-limit rejections) are documented inline.

invalid_credentialHTTP 401

Bearer header missing, malformed, or hash didn't match an active credential. Re-issue the credential and update the client config.

invalid_inputHTTP 400

Input failed Zod validation (missing required field, extra property, wrong type). The message names the offending field.

tier_gateHTTP 403

Account is on the free tier and the call hit a paid-only tool (subscription.cancel or subscription.negotiate). Upgrade to unblock.

rate_limitHTTP 429 · Retry-After

Per-credential per-tool-class budget exhausted. The Retry-After header carries the wait time in seconds.

audit_not_foundHTTP 404

audit.query was passed an audit_id that doesn't exist or doesn't belong to the caller's workspace.

subscription_not_foundHTTP 404

subscription.cancel / subscription.negotiate received a subscription_id that doesn't exist or doesn't belong to the caller's workspace.

subscription_not_found_by_nameHTTP 404 · candidates[]

subscription.cancel was given a vendor_name with multiple matches. The response includes a candidates array of {subscription_id, vendor_name}; re-call with the chosen subscription_id.

no_target_priceHTTP 422

subscription.negotiate needs a target_price. Call benchmark.lookup first and pass benchmark.price_low or .price_typical.

tool_errorHTTP 500

Unexpected internal error. Spendrein captures these with full traces — the assistant should surface a friendly message and offer to retry.