Connect Claude — or any MCP client — to your factory

QuarterMaster ships a hosted MCP server at https://api.quarter-master.co/mcp. Every request is authenticated as you — a personal API key for header-based clients (Claude Code, the Claude API), or a per-user OAuth sign-in for connector surfaces (claude.ai, Grok) — so every answer is scoped to your org and every action is attributed to you. Reads are grounded in the live ledger; the one write tool drafts a PO that always lands pending human approval.

1 · Create your personal API key

Any member can mint a personal key from a signed-in session. Personal keys act as you: their scopes are clamped to your current role at every request, and they can never carry admin or approve:purchase_orders — an agent can draft, only a human can approve. Revoke anytime with DELETE /v1/api-keys/{id}; keys die automatically if you leave the org.

curl -X POST https://api.quarter-master.co/v1/api-keys \
  -H "Authorization: Bearer $QM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude on my laptop",
    "personal": true,
    "scopes": ["read:inventory", "read:costing", "write:purchase_orders"]
  }'

# → { "key": "qm_live_1a2b3c4d_…", … }   ← save it; it is never shown again
export QM_MCP_KEY="qm_live_1a2b3c4d_…"

Just exploring? POST /v1/guest/session provisions a throwaway demo factory and returns a ready-made mcpApiKey for it — no account needed.

2 · Connect Claude Code

claude mcp add --transport http quartermaster https://api.quarter-master.co/mcp \
  --header "Authorization: Bearer ${QM_MCP_KEY}"

For a shared repo, commit a .mcp.json that references the env var — each teammate exports their own key and gets their own attribution:

{
  "mcpServers": {
    "quartermaster": {
      "type": "http",
      "url": "https://api.quarter-master.co/mcp",
      "headers": { "Authorization": "Bearer ${QM_MCP_KEY}" }
    }
  }
}

3 · Connect claude.ai or Grok — OAuth, no keys to paste

Connector surfaces can't carry a per-user header, so the server is also a full OAuth 2.1 authorization server (PKCE S256, dynamic client registration, rotating refresh tokens). Add the connector, and your browser opens a QuarterMaster consent screen: sign in, pick the org and the scopes the agent gets, done. Each teammate connects as themselves.

claude.ai / Claude Desktop — Settings → Connectors → Add custom connector → paste https://api.quarter-master.co/mcp. Claude discovers the OAuth endpoints itself and walks you through the consent screen.

Grok — grok.com/connectors → New Connector → Custom → paste https://api.quarter-master.co/mcp and complete the sign-in when prompted.

Grants clamp to your role on every request (a demotion applies immediately), can never carry admin or approve:purchase_orders, and die when you disconnect the connector, leave the org, or delete your account.

4 · Other clients

Claude API — pass the server in mcp_servers with authorization_tokenset to the user's key; your backend supplies each user's own token per request.

Claude Desktop (local stdio) — run the server as a local process against your own deployment; the key comes from the environment:

{
  "mcpServers": {
    "quartermaster": {
      "command": "uv",
      "args": ["run", "python", "-m", "qm_api.mcp_server"],
      "env": {
        "QM_MCP_TRANSPORT": "stdio",
        "QM_MCP_API_KEY": "qm_live_…",
        "QM_DATABASE_URL": "postgresql+asyncpg://…"
      }
    }
  }
}

Run it locally

cd apps/api && uv sync
uv run uvicorn qm_api.main:app --reload        # API + MCP on :8000

# demo key in one line (jq):
curl -s -X POST localhost:8000/v1/guest/session \
  -H 'Content-Type: application/json' -d '{"deviceId":"my-laptop-01"}' | jq -r .mcpApiKey

claude mcp add --transport http qm-local http://localhost:8000/mcp \
  --header "Authorization: Bearer ${QM_MCP_KEY}"

The security model, in six lines