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, en, fr, es, it, pl, ro, nl, el or hu, default de — which 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):

list_search_filters

Discovers which filters search_references accepts for your company. Requires the search scope.

Global filters (location, period, contract value, …) work in every search. The branch-specific ones — work fields, methods and your industry's additional fields — depend on what your company has configured, so an AI client cannot guess them. This tool returns exactly the ones you can use, including the valid option IDs.

Response (structuredContent):

Filter discovery

Branch-specific filtering is a three-step conversation:

Values in the filters object depend on the field's kind:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "search_references",
    "arguments": {
      "branch_ID": 828,
      "country": "DE",
      "contract_value_from": 250000,
      "method_ID": 55,
      "filters": { "f21": "1000-", "f40": true }
    }
  }
}

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()