MCP server for the Dealops AI quoting agent

Exposes the AI-quoting pipeline as MCP tools so Claude (or any MCP host) can orchestrate quote generation — with a hosted, API-key-authed endpoint on the main server.

1. Why this exists

Dealops has an AI-quoting pipeline that takes a Salesforce opportunity and produces a V2 pricing quote. Today, Stage 4 of that pipeline (Gemini) is the orchestrator — it reads context, calls comparables, picks SKUs, sets prices, and writes the quote.

This PR ships an MVP that inverts that control flow. The same deterministic capabilities (fetch opportunity context, find similar accounts, analyze pricing benchmarks, resolve a pricebook, persist a quote) are exposed as Model Context Protocol tools. An MCP host like Claude Desktop or Claude Code becomes the brain and decides which tools to call, in what order, with what arguments.

2. Two ways to run the same tools

The PR provides both a standalone process (for local dev) and a hosted endpoint mounted on the main server. They share the transport plumbing (httpShared.ts) and the server factory (server.ts); they differ only in how they authenticate and where they get the quote author from.

3. The tools the host gets

Read tools carry readOnlyHint: true; only create_pricing_quote writes. Each tool wraps an existing pipeline function (single source of truth) and returns JSON text.

4. The orchestration the host is expected to run

The build_quote prompt encodes this. None of it is hard-wired in the server.

5. Shared validateApiKey: factoring the auth path

To support both the tRPC external API and the new MCP endpoint with one source of truth, the API-key validation logic is extracted into apps/server/src/lib/apiKey/validateApiKey.ts.

// trpc/middleware/apiKeyAuth.ts — now
const validated = await validateApiKey(apiKey);
if (!validated) throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid API key.' });
return next({ ctx: { ...ctx, organization: validated.organization,
                     user: validated.user, apiKey: validated.apiKey } });

6. Two safety guards against writing to prod Plaid

The only mutating tool is create_pricing_quote, and the design wants it to persist only to the Plaid Test Org. Three layers enforce that.

7. Authorization: don't trust the cached role

The hosted endpoint's auth middleware does two distinct checks. The second is the careful one.

8. Per-request server, stateless transport

Both entry points share httpShared.ts, which constructs a fresh McpServer + StreamableHTTPServerTransport per POST and tears them down on connection close. GET and DELETE return JSON-RPC method not allowed (no server-push, no sessions).

// routes/quotingMcp.ts — the hosted handler
router.post('/quoting', authenticate, async (req, res) => {
  const userId = req.mcpUserId ?? null;
  // Per-request server so create_pricing_quote attributes to the key's user.
  const server = createQuotingMcpServer({ ...config, userId });
  await handleStatelessMcpPost(server, req, res);
});

9. Stage-5 hardening on create_pricing_quote

The write path adds checks that would have been implicit in the SSE pipeline but matter when an external host is composing the input.

10. Calculation-trace logic, deduplicated

Both the tRPC pricingEngine.explainQuote handler and the new MCP explain_quote tool need the same logic: prefer a stored milestone trace, otherwise recompute ephemerally from the saved quote input. That logic moves into a new service.

11. Admin UI to mint keys

A new internal-staff-only Admin tab, MCP Setup, lets staff generate / revoke API keys and copy a ready-to-paste connection snippet for Claude Code or Claude Desktop.

// Generated snippet (key filled in by the "new key" modal)
claude mcp add --transport http dealops-quoting \
  https://<host>/api/mcp/quoting \
  --header "Authorization: Bearer <dealops-api-key>"

12. What it doesn't change

13. Risks & open questions