MCP Server

The Pyramid AI MCP server exposes your organization’s document corpus over the Model Context Protocol — an open standard for connecting AI assistants to external tools and data. Any MCP-aware client (Claude, Cursor, or a custom agent built on the MCP SDK) can search your documents and get back grounded answers with source links, without you writing a line of integration code.

Endpoint

POST https://api.pyramid-ai.com/api/v2/mcp

• Transport: Streamable HTTP, stateless — one POST per JSON-RPC exchange, no session to manage.
• Only POST is served; GET and DELETE return a JSON-RPC 405.

Connect in under 5 minutes

Authentication

The MCP endpoint uses the same bearer API-key auth as every other Pyramid AI API route — no OAuth flow. Send your key in the Authorization header, and because the transport is Streamable HTTP, your client must advertise both content types in Accept:

Authorization: Bearer pai_live_YOUR_KEY_HERE
Content-Type: application/json
Accept: application/json, text/event-stream

Responses come back as a one-shot SSE frame (event: message / data: <json-rpc>). Most MCP clients and SDKs handle this framing for you.

Connect your client

Claude Code

claude mcp add pyramid-corpus --transport http \
  https://api.pyramid-ai.com/api/v2/mcp \
  --header "Authorization: Bearer pai_live_YOUR_KEY_HERE"

Claude Desktop / Cursor

Add the server to your mcpServers config (claude_desktop_config.json for Claude Desktop, .cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "pyramid-document-corpus": {
      "type": "http",
      "url": "https://api.pyramid-ai.com/api/v2/mcp",
      "headers": { "Authorization": "Bearer pai_live_YOUR_KEY_HERE" }
    }
  }
}

Custom agent (TypeScript SDK)

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const transport = new StreamableHTTPClientTransport(
  new URL('https://api.pyramid-ai.com/api/v2/mcp'),
  { requestInit: { headers: { Authorization: 'Bearer pai_live_YOUR_KEY_HERE' } } },
);
const client = new Client({ name: 'my-agent', version: '1.0' });
await client.connect(transport);
const result = await client.callTool({
  name: 'answer_question',
  arguments: { query: 'What are the requirements for road opening works?' },
});

MCP Inspector (visual debugging)

npx @modelcontextprotocol/inspector

Choose transport Streamable HTTP, set the URL to the endpoint, and add the Authorization: Bearer … header.

Tools

The server exposes two tools. Both accept the same arguments — the difference is whether you want raw hits to reason over yourself, or a finished, cited answer.

Shared arguments

search_documents

Hybrid (semantic vector + full-text BM25) search over the corpus, returning ranked documents with their source links. The tool result is a JSON payload:

{
  "query": "bamboo scaffolding",
  "scope": "technical_circulars",
  "requestedScope": "technical_circulars",
  "broadened": true,
  "hasResults": true,
  "count": 1,
  "results": [
    {
      "title": "DEVB TC(W) No. 1/2025",
      "url": "https://www.devb.gov.hk/tcw-1-2025.pdf",
      "snippet": "Guidance on bamboo scaffolding...",
      "score": 0.91,
      "edition": null,
      "versionStatus": "current",
      "publishedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "versionPolicy": "current"
}

Always surface results[].url to the user — it is the canonical source link. When hasResults is false, tell the user nothing relevant was found and ask them to refine; do not answer from prior knowledge.

Editions

Results come from the current edition of each document unless you pass versionPolicy: "all". Every result says which edition it is: edition (e.g. "2026 Edition", or null when the document has a single edition), versionStatus ("current" or "superseded") and, for a superseded edition, supersededBy (the title of the current one). When you show a result to a user, name its edition; never present a superseded result as current. A date range (startDate/endDate) returns documents published in that range and, for documents with editions, the edition that was in force then.

answer_question

Runs the same hybrid search, then synthesizes a complete written answer from the top passages, with bracketed [n] citation markers. The answer is atomic — it arrives whole after ~20–25s (MCP tool results cannot stream).

{
  "query": "what are the requirements for road opening works?",
  "answer": "Road opening works must follow the permit conditions [1]...",
  "hasResults": true,
  "scope": "default",
  "requestedScope": "default",
  "broadened": false,
  "citations": [
    { "ref": 1, "title": "HyD TC No. 5/2024", "url": "https://..." }
  ],
  "sources": [
    { "ref": 1, "title": "HyD TC No. 5/2024", "url": "https://...", "snippet": "...", "score": 0.88 }
  ]
}

• citations is the subset of sources the answer actually references via its [n] markers.
• sources lists every passage the search retrieved, whether or not it was cited.
• The payload is also returned as structuredContent for SDK clients that prefer structured parsing.

Scope & broadening

A narrow scope is a relevance hint, not a hard filter. When you pass a narrow technical scope, the search runs over the broad technical pool so a wrong category guess can’t hide the right document — and the response sets broadened: true with your original choice preserved in requestedScope. Results may therefore include other document types.

• answer_question will prefer the requested document type and add a caveat in the answer when it relies on another.
• press_releases and everything are exact — they are never broadened.

A hasResults: false response means nothing ranked as relevant; it does not prove the document doesn’t exist. Refine the query rather than concluding the corpus lacks coverage.

Progress updates

MCP tool results don’t stream, but answer_question emits coarse notifications/progress while it works — if your call opts in with a progressToken in the request _meta:

"params": {
  "name": "answer_question",
  "arguments": { "query": "..." },
  "_meta": { "progressToken": "t1" }
}

Stages: Searching the document corpus… (10/100) → Retrieved N documents — generating answer… (40/100) → Answer ready. (100/100). SDK clients receive these via the onprogress callback on callTool. Budget a 60-second client-side timeout for answer_question.

Raw JSON-RPC (curl)

For testing or non-SDK clients, call the JSON-RPC API directly. The Accept header must advertise both content types:

curl -sS https://api.pyramid-ai.com/api/v2/mcp \
  -H "Authorization: Bearer pai_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_documents",
      "arguments": { "query": "bamboo scaffolding safety requirements" }
    }
  }'

List the available tools with "method": "tools/list".

Troubleshooting

Next steps