Skip to main content

MCP server overview

The Evenhand MCP server exposes deal-scoped reads and a tightly gated set of writes as Model Context Protocol tools. It lets an authenticated user ask natural-language questions about their deals from Claude Desktop — or any MCP-compatible client — and have the assistant call structured, auditable, RLS-bounded tools on their behalf.

The server authenticates the user, then rehydrates the same session context the web app uses. Postgres row-level security evaluates every tool call exactly as it would for a request from the web app. The tool surface is what changes; the visibility rules do not.

Transport​

  • Protocol. JSON-RPC 2.0 over MCP Streamable HTTP. One POST per request, no SSE.
  • Endpoint. POST https://mcp.evenhandhq.com/api/mcp/v1/server
  • Server name. evenhand-deals, advertised in the initialize response.
  • MCP protocol version. 2025-03-26.

Every request carries Authorization: Bearer <access_token>. Missing, malformed, expired, or revoked tokens return HTTP 401.

Read tools​

Twelve read tools cover the surface a buyer typically asks about: deals and participants, QoE progress and P&L, customer concentration, Q&A, documents (metadata only — bodies are never returned over MCP), offers, closing conditions, and forward-referenced findings and financing-stack tools that return a structured feature_not_available response until their backing build steps ship. See Tools reference.

Write tools​

Seven write tools cover question submission, QoE normalization adjustments, and forward-referenced finding and financing-source mutations. Writes pass three gates before they execute — scope, per-tool grant, and per-deal opt-in. The default state of every grant and opt-in is off. See Write gating.

OAuth model​

The server speaks OAuth 2.1 with PKCE. A user registers a client at Settings → Connected MCP clients in the web app, completes a one-time authorization-code flow, and receives:

  • An access token with a 1-hour TTL.
  • A refresh token with a 30-day TTL, rotated on every use.

Scopes are coarse: mcp:read (granted by default) and mcp:write (separate consent, layered with the per-tool and per-deal gates above). See Authentication.

Connect with Claude Desktop​

  1. Register a client. In the Evenhand web app, open Settings → Connected MCP clients, click Register client, give it a name (e.g. Claude Desktop), and copy the redirect URI from Claude Desktop's MCP settings into the form. Save.

  2. Point Claude Desktop at the server. In Claude Desktop's MCP configuration, add an entry that uses https://mcp.evenhandhq.com/api/mcp/authorize as the authorization URL, https://mcp.evenhandhq.com/api/mcp/token as the token URL, and https://mcp.evenhandhq.com/api/mcp/v1/server as the MCP server URL. Use PKCE method S256 and request scope mcp:read (or mcp:read mcp:write if you want writes).

  3. Approve in the browser. Claude Desktop opens the Evenhand consent screen in your browser. Click Allow. Tokens are minted and the server is ready to call. Test it by asking Claude List my deals.