MCP Server Documentation

Overview

This MCP (Model Context Protocol) server provides a set of tools for searching and retrieving information about events, points of interest (POIs), trails, and protected areas (in the context of trails) from a knowledge graph. It is designed to be consumed by MCP-compatible clients via JSON-RPC 2.0. All tools return JSON-LD as structured content.

MCP Server

Server URL: https://proxy.opendatagermany.io/api/its/mcp

Authentication is done via x-api-key header. Contact DZT[email protected]. for an API key.

Listing and Calling Tools

This MCP server follows the standard Model Context Protocol (MCP) interaction pattern. Clients typically perform two core actions:

1. List available tools exposed by the server
2. Invoke (call) a specific tool with a structured JSON input

Listing Tools

To discover which tools the server provides, the client issues a JSON-RPC request to list tools. The server responds with a list of tool definitions, including names, descriptions, and input schemas.

Example: List Tools Request

{
  "jsonrpc": "2.0",
  "id": "list-tools",
  "method": "tools/list"
}

Example: List Tools Response (Excerpt)

{
  "jsonrpc": "2.0",
  "id": "list-tools",
  "result": {
    "tools": [
      {
        "name": "get_events_by criteria",
        "description": "An Event search MCP server Application that allows the user to look up events by various criteria.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "keywords": { "type": "string" }
          }
        }
      },
      {
        "name": "get_trails_by_criteria",
        "description": "Searches a knowledge graph for hiking and bike trails and tours based on various criteria.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "difficulty": { "type": "string" },
            "max_length_km": { "type": "number" }
          }
        }
      },
      "..."
    ]
  }
}

Clients should rely on the returned inputSchema to validate and construct tool calls dynamically.

Calling a Tool

To invoke a tool, the client sends a JSON-RPC request using the tool name as the method and supplies arguments that conform to the tool’s inputSchema.

Example: Tool Call Request

{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tools/call",
  "params": {
    "name": "get_trails_by_criteria",
    "arguments": {
      "region": "Nördlicher Schwarzwald",
      "keywords": "familienfreundlich,Kinder,geeignet für Familien"
    }
  }
}

Example: Tool Call Response (Excerpt)

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "{\"@context\":{\"schema\":\"https://schema.org/\",\"odta\":\"https://odta.io/voc/\"},\"@graph\":[{...}]}"
      }
    ],
    "structuredContent": {
      "@graph": [
        {
          "@id": "https://mein.toubiz.de/api/v1/article/6113299e-fb48-4f44-b4e8-570b54780947",
          "@type": "https://odta.io/voc/Trail",
          "schema:name": "GeoTour Calw - Wo aus Wasser Steine werden",
          "schema:description": "<p><strong>Wo aus Wasser Steine werden</strong></p>..."
        },
        "...",
        {
          "@id": "https://mein.toubiz.de/api/v1/article/8ce08d6e-eca5-11ee-9b6f-00163e2945d0",
          "@type": "https://odta.io/voc/Trail",
          "schema:name": "Holzfigurenpfad - Familienfreundliche Tour",
          "schema:image": "https://mein.toubiz.de/api/v1/media/3dfa1d44-2e9c-11ef-9a73-00163e2945d0/view",
          "schema:description": "<p>Hier handelt es sich um die kinderwagentaugliche Variante...</p>"
        }
      ],
      "@context": {
        "odta": "https://odta.io/voc/",
        "schema": "https://schema.org/"
      }
    }
  }
}

Important Notes

• Tool arguments must conform to the published inputSchema.
• Clients should treat tool responses as opaque domain data and avoid hard-coding assumptions.

Tools

1. get_events_by_criteria

Description Allows users to look up events using various criteria.

Input Schema

Output Schema

See: https://semantify.it/ds/RbeFyqmMLixF

2. get_pois_by_criteria

Search for Points of Interest using flexible criteria.

Description Searches the knowledge graph for POIs such as museums, restaurants, landmarks, and other places. Multiple filters can be combined.

Input Schema

Note that typewill be processed string-based with fuzzy-search. A query for Sauna would return also SaunaPark instances.

Output schema

See: https://semantify.it/ds/mRvUvwHcgDIW

3. get_trails_by_criteria

Search for hiking and biking trails using advanced filters.

Description Searches the knowledge graph for trails and tours, supporting difficulty, length, region, and geospatial constraints.

Input Schema

Output Schema

See: https://semantify.it/xReUJzvHPcGt

4. get_entity_details

Retrieve detailed information about an entity.

Description Returns full entity details according to its ODTA Domain Specification.

Input Schema

Output Schema

The output schema is the ODTA Domain Specifications v1.4 (for backward compatibility) and v2.1. Every instance in the result has a https://vocab.sti2.at/ds/compliesWith property with a domain specification URI. This URI can be called with content negotiation as JSON-LD in order to obtain a machine understandable representation of the schema. See a full list of available entity types and schemas: https://semantify.it/list/CRkyvcqGqeUu

Notes & Best Practices

• Agents consuming the MCP Server should be able to combine multiple tool calls. For example, After receiving the basic information about an event, it is possible to retrieve detailed information of that event by calling the get_entity_details tool. Instances with legacy DZT Domain Specifications are not supported by get_entity_details tool.
• Keyword fields expect comma-separated values unless stated otherwise.
• In their corresponding tool results, all subtypes of Place, Event and Trail are available. All properties in the specified output schema for a specific tool are available for each subtype. The type hierarchy can be seen here: https://semantify.it/voc/unGdYZATQmET?mode=tree

Versioning & Extensibility

This MCP server is designed to be extensible. Additional tools, filters, and entity types (e.g. accommodations, tours, gastronomy) can be added without breaking existing integrations. As a best practice, agents should do a tool list call with a certain frequency so that the LLM can work with the latest tools specification.

In principle, there should be no static integrations with MCP servers as the tool listing call always provides and updated list of tools. Still, to support clients that have static integrations with the MCP Server, we keep the old tools get_event_details, get_trail_details, get_poi_details and get_protected_area but mark them as DEPRECATED in their descriptions. These tools are now replaced with get_entity_details and will be removed from the server soon. Morever, event_search_name_and_keyword tool is renamed as get_events_by_criteria to make it more generic.

Appendix: A typical agentic workflow

Note that this image is only informative. Names of tools and output schema may differ from the actual implementation.

Appendix B: How to retrieve data from the MCP Server

The MCP server provides data in a way that makes it easy to use in no-code tools like n8n. Data retrieval always happens in two simple steps: first an overview, then the details.

Step 1: Show available objects (overview)

First, n8n retrieves a list of all available objects. This list contains only basic information, for example:

• the URI of the object
• a name or title
• a short description
• an image

The goal of this step is to select an object of interest from a list of objects, not to load all details.

In n8n, this step appears as an action such as “List objects” or “Fetch list.”

Step 2: Retrieve details for an object

Once an object has been selected, its full information can be loaded. For this, a second step is executed in which the object URI and a two-letter language code is passed to the get_entity_details tool.

All available properties of this object are returned. The amount of information and type of properties vary depending on the object type.

In n8n, this is usually an action such as “Get object details.”

Why two steps?

This approach is deliberately designed this way:

• Clear and structured: select first, then dive into details
• Fast: only the data that is actually needed is loaded

Typical workflow in n8n

1. Select the MCP server
2. Run the “List objects” action
3. Select the desired object
4. Run the “Get object details” action
5. Reuse the data in the workflow