Skip to main content
citehouse.

MCP integration

The Citehouse MCP server exposes the gateway as a standard Model Context Protocol server. Any MCP-compatible client can connect, list tools, and call query_standard to retrieve from licensed engineering corpora.

Prerequisites

  • Node.js 20 or later.
  • An issued Citehouse API key. Pilot keys are scoped to the ASME corpus.
  • An MCP client. The example below uses the official @modelcontextprotocol/sdk.

Install the SDK

npm install @modelcontextprotocol/sdk

Connect and list tools

import { McpClient } from "@modelcontextprotocol/sdk/client";

const client = new McpClient({
  url: "https://mcp.citehouse.com",
});

await client.connect({
  apiKey: process.env.CITEHOUSE_KEY,
});

const tools = await client.listTools();
console.log(tools.map((t) => t.name));
// => ["query_standard", "lookup_section", "cite_passage", "list_corpora"]

Call query_standard

query_standard is the primary retrieval tool. It accepts a natural-language question, a token budget, and an optional society filter, and returns up to K matched sections with canonical citations.

const result = await client.callTool("query_standard", {
  question:
    "What is the minimum required wall thickness for B31.3 process piping?",
  max_tokens: 1200,
  society_filter: ["ASME"],
});

for (const passage of result.passages) {
  console.log(`${passage.citation}\n${passage.text}\n`);
}

Response shape

{
  "passages": [
    {
      "society": "ASME",
      "standard": "B31.3",
      "section": "§304.1.2",
      "text": "The minimum required thickness, t, shall be ...",
      "citation": "[ASME B31.3 §304.1.2]"
    }
  ],
  "tokens_returned": 482,
  "latency_ms": 612,
  "ledger_entry_id": "le_01JG9..."
}

The ledger_entry_id cross-references the metered call on your monthly invoice. It is safe to log and replay against GET /api/v1/calls/:id for audit.

Error handling

The gateway surfaces three error categories you should handle explicitly:

| Error | Cause | Recommended action | | --- | --- | --- | | 401 Unauthorized | Missing or invalid API key | Refresh your key from the dashboard | | 402 Payment Required | x402 handshake required | Retry with the settlement token (see x402) | | 429 Too Many Requests | Tier rate limit exceeded | Back off per the Retry-After header; consider a higher tier |

Latency notes

  • The gateway caches embeddings; the embedding step is paid once at indexing, not per call.
  • A typical Tier 2 call returns in 400–700 ms.
  • Calls that opt into LLM rerank/synthesis (set rerank: true) add 200–600 ms but materially improve relevance on dense PDFs.

Next

  • Citation format — the structure of the citation block returned with every passage.
  • x402 integration — for agents that pay per call without a pre-issued API key.