MCP Integration

TrustRelay ships a built-in Model Context Protocol (MCP) server that lets AI agents — such as Claude, Cursor, and other MCP-compatible tools — discover and query data products directly.

The MCP server uses the Streamable HTTP transport (protocol version 2025-03-26) and authenticates via Personal Access Tokens.

Endpoint

Both paths support GET, POST, and DELETE methods as required by the streamable HTTP transport. There is no timeout on MCP connections — they are long-lived by design.

Authentication

MCP endpoints do not use browser session cookies. You must authenticate with a Personal Access Token passed as a Bearer token:

Authorization: Bearer <your-pat>

See Personal Access Tokens to create one.

Connecting Claude Desktop

Add TrustRelay to your claude_desktop_config.json:

{
  "mcpServers": {
    "trustrelay": {
      "url": "https://your-trustrelay-instance.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-pat>"
      }
    }
  }
}

Replace your-trustrelay-instance.example.com with your deployment URL and <your-pat> with a token created in User Settings → Developer.

Connecting via MCP Inspector or other clients

Any MCP-compatible client can connect by pointing to the /mcp endpoint with the Authorization header:

POST https://your-instance.example.com/mcp
Authorization: Bearer <your-pat>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "1.0.0" }
  }
}

What the MCP server exposes

The TrustRelay MCP server provides tools for searching and querying published data products. Agents can:

• Search the product catalog by keyword or category
• Inspect a product’s schema, SLA, license, and usage documentation
• Query product data directly via DuckDB — the server loads connection credentials at startup and executes named SQL queries against the underlying data sources on behalf of the agent

Specific tool names and input schemas are advertised dynamically via the tools/list MCP method when a client connects.

JSON-RPC query endpoint

For direct programmatic queries (outside of MCP), TrustRelay also exposes a JSON-RPC 2.0 endpoint:

POST /api/jsonrpc
Authorization: Bearer <your-pat>   (or session cookie)
Content-Type: application/json

This endpoint has a 60-second timeout (longer than the 30-second default for other routes) to accommodate long-running analytical queries. It executes named queries defined in a product’s Usage Info section against the DuckDB connection pool.

DuckDB and credential loading

At startup, the TrustRelay API loads credentials for all published data products into a shared DuckDB connection pool. This enables low-latency query execution without round-tripping to external credential stores on every request.

Credential fields loaded per product:

When a new product is published, the credential pool is updated without a server restart.

DXF export

TrustRelay also supports exporting geospatial query results as DXF (AutoCAD) files:

POST /api/export/dxf
Authorization: Bearer <your-pat>   (or session cookie)
Content-Type: application/json

The request body accepts a GeoJSON FeatureCollection. The response is a binary application/dxf file attachment.