MCP Gateway Reference

The MCP gateway exposes your company's reference data to AI assistants and agent frameworks via the Model Context Protocol (MCP) — an open JSON-RPC 2.0 standard supported by Claude, ChatGPT, Microsoft Copilot Studio, Cursor, n8n, LangChain, and most agent SDKs. This page is the complete technical reference: every callable tool with its parameters, all readable resources, the built-in prompts, and the error model.

For token management, scope administration, and usage monitoring in the app, see AI Access (MCP Gateway).

Endpoint & transport

A server-initiated SSE channel (GET on the endpoint) is not yet available and currently responds with 501.

Authentication

Every request must present an MCP token, created by a Company Admin in the app under AI / MCP Gateway:

Requests without a valid token receive 401 with JSON-RPC error -32001 / -32002. Expired and revoked tokens are rejected the same way.

Scopes

Each token carries a set of scopes chosen at creation time. Tools are both hidden from tools/list and blocked on tools/call when their scope is missing (error -32003).

Rate limits

60 requests per minute per token. Exceeding the limit returns 429 with a Retry-After: 60 header and JSON-RPC error -32005.

JSON-RPC methods

Batch requests (a JSON array of request objects) are supported. Requests without an id are treated as notifications and answered with 204 No Content.

Example request

curl -X POST https://referenzen.com/mcp/v1 \
  -H "Authorization: Bearer dby_mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_references",
      "arguments": { "query": "bridge", "limit": 5, "lang": "en" }
    }
  }'

Tool results always come in two parallel representations:

• content — an array of MCP content blocks: a human-readable Markdown text block plus resource_link blocks pointing to canonical references://<id> URIs (used by chat clients for display and citation).
• structuredContent — a machine-readable JSON object (used by code-driven agents). The field tables below describe structuredContent.

Tools

All tools accept an optional lang parameter ("de" or "en", default "de") that controls the language of returned titles, descriptions, branch names, and formatted values.

search_references

Full-text search across your reference projects, backed by the platform search engine. Requires the search scope.

Response (structuredContent):

get_reference

Full detail of a single reference project. Requires the read scope. The reference must belong to your company and be published on the API channel; otherwise the call fails.

Response (structuredContent) — fields are present when the reference has content for them:

list_references

Plain paginated listing without full-text search — useful for browsing by branch, reference group, or period. Requires the read scope.

Response (structuredContent): total, page, limit, and results — items carry reference_ID, uri, title, city, country, yearfrom/monthfrom, yearuntil/monthuntil, plus detail_url (the public reference page) and thumb_url (preview image) where available.

list_branches

The industry/branch tree, one level at a time. Requires the read scope.

Response (structuredContent):

list_referencegroups

Your company's own reference groups (custom categories). Requires the read scope.

Response (structuredContent):

get_company_profile

Your own company profile — useful context for the connected assistant. Requires the read scope.

Response (structuredContent):

list_clients

Distinct clients/customers from your reference projects. Requires the read and client_details scopes.

Response (structuredContent):

get_reference_media_urls

Direct URLs for all media files of a reference project. Requires the media scope.

Response (structuredContent):

get_statistics

View-count statistics for your references. Requires the analytics scope.

Response (structuredContent) depends on type:

• total — total view count for the period.
• by_branch / by_referencegroup — views grouped by branch or reference group.
• top_references — top_references array with reference_ID, title, viewcount.
• trend — current_period and previous_period objects (from, to, views) plus the absolute change.

match_references

The RFP-matching tool: given a tender text, project brief, or topic description, it returns your best-matching references ranked by relevance. Long inputs are reduced server-side by key-phrase extraction — no pre-summarising needed. Requires the search scope.

Response (structuredContent):

Resources

Resources are read-only documents addressable by stable URIs, retrieved with resources/read. AI clients can cite these URIs and re-fetch them later. Concrete resources (from resources/list):

URI templates (from resources/templates/list):

All resources return mimeType: application/json with the payload serialized in the text field of the contents entry.

Prompts

Built-in prompt templates, discoverable via prompts/list and fetched with prompts/get. They return ready-to-run message sequences that instruct the connected assistant which tools to call.

Errors

Errors follow JSON-RPC 2.0 with MCP-specific codes:

Client configuration

{
  "mcpServers": {
    "references": {
      "type": "http",
      "url": "https://referenzen.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer dby_mcp_YOUR_TOKEN"
      }
    }
  }
}

import os
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "references": {
        "transport": "streamable_http",
        "url": "https://referenzen.com/mcp/v1",
        "headers": {"Authorization": f"Bearer {os.environ['MCP_TOKEN']}"},
    }
})
tools = await client.get_tools()