TomTom Model Context Protocol (MCP) server

TomTom Model Context Protocol (MCP) server

The TomTom Model Context Protocol (MCP) server is a service that enables AI agents to invoke geospatial tools through a standardized MCP interface.

The TomTom Model Context Protocol (MCP) server supports the following core capabilities:

• Routing. Compute optimal routes (single/waypoint) with live traffic and vehicle constraints.

• Search. Address, POI, and fuzzy place search.

• Geocoding / reverse geocoding. Precise coordinate and address translation.

• Reachable range. Isochrone (area reachable within time/distance).

• Traffic incident. Real-time incident alerts.

• Static map rendering. Generate static map visuals.

Model Context Protocol overview

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.

Key benefits are the following:

• Standardization. Eliminates the need for custom integrations between each AI application and tool.

• Interoperability. Any MCP-compatible client can connect to any MCP server.

• Scalability. Transforms the M×N integration problem into M+N.

• Security. Built-in authentication and access control mechanisms.

Architecture overview

This section provides a high-level view of the system architecture, detailing its key components and communication flow to illustrate how the TomTom MCP server integrates with client applications using industry-standard protocols.

System components

Based on the architecture diagram, the TomTom MCP server consists of:

• MCP client. The AI application or agent that initiates requests using JSON-RPC protocol.

• TomTom MCP server. Acts as a bridge between MCP protocol and TomTom APIs.

• Tools layer. Exposes TomTom capabilities as standardized MCP tools.

• TomTom Core APIs. The underlying geospatial services accessed via HTTP + API key.

Communication flow

The communication flow between the client and server ensures compatibility with industry standards used by providers like Anthropic and OpenAI:

• Communication follows JSON-RPC 2.0 over STDIO, matching industry implementations by Anthropic, OpenAI, and others.

• The server supports client handshake (listTools) and tool invocation (route, search, etc.) responses with structured JSON and optional base64 map images.

• API key authentication is handled server-side, keeping credentials secure.

Detailed tool definitions

The TomTom MCP server exposes the following tools:

Implementation of JSON-RPC 2.0 protocol

Request format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tools/call",
  "params": {
    "name": "tomtom-routing",
    "arguments": {
      "origin": {
        "lat": 52.3791,
        "lon": 4.8994
      },
      "destination": {
        "lat": 52.5200,
        "lon": 13.4050
      }
    }
  }
}

Response format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "routes": [
      {
        "summary": {
          "lengthInMeters": 659823,
          "travelTimeInSeconds": 23421
        }
      }
    ]
  }
}

Error handling

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Missing required field: destination"
  }
}

Internal flow and execution

The following steps outline the execution process:

1. Client invokes tool via JSON-RPC. The MCP client sends a standardized request.

2. Server validates parameters. Input validation against tool schemas (Zod or JSONSchema).

3. Server performs HTTP call to TomTom API. Includes API key authentication.

4. Response formatting. API response is converted to MCP-compliant JSON format.

5. Response delivery. Result streamed back over SDR/HTTP to the AI model.

Example: routing request flow

The following flow represents routing request processing:

Transport mechanisms

STDIO transport (local)

• Server reads JSON-RPC messages from stdin

• Writes responses to stdout

• Error logging via stderr

• Ideal for local tool integration

Tool implementation examples

Geocoding tool

Request

{
  "method": "tools/call",
  "params": {
    "name": "tomtom-geocode",
    "arguments": {
      "query": "Amsterdam Central Station",
      "countrySet": "NL",
      "limit": 5
    }
  }
}

Processing steps

Processing steps are the following:

1. Extract and validate query parameters.

2. Construct TomTom Geocoding API request.

3. Add authentication (API key).

4. Parse API response.

5. Return standardized MCP response.

Routing with traffic

Request

{
  "method": "tools/call",
  "params": {
    "name": "tomtom-routing",
    "arguments": {
      "origin": { "lat": 52.3791, "lon": 4.8994 },
      "destination": { "lat": 52.5200, "lon": 13.4050 },
      "routeType": "fastest",
      "traffic": true,
      "vehicleType": "car"
    }
  }
}

Routing with traffic has the following features:

• Real-time traffic consideration.

• Multiple route types (fastest, shortest, eco, thrilling).

• Vehicle-specific routing (car, truck, pedestrian, bicycle).

• Traffic delay calculations.

Use case scenarios

This section highlights practical use case scenarios that demonstrate how the system supports advanced routing, real-time traffic handling, service area analysis, and route visualization for various vehicle types and operational needs.

Routing heavy or EV vehicles with traffic constraints

• Vehicle dimension restrictions (height, weight, length).

• EV-specific routing with charging stations.

• Hazardous material routing restrictions.

• Real-time traffic avoidance.

Isochrone-based service area analysis

• Determine reachable areas within time/distance budgets.

Live ETA predictions with traffic incidents

• Real-time traffic integration.

• Incident impact on route timing.

• Alternative route suggestions.

• Dynamic rerouting capabilities.

Map visualizations for route context

• Static map generation with routes overlay.

• Custom styling options.

Getting started

Prerequisites and installation

• TomTom Developer Account and API key.

• MCP-compatible client (e.g., Claude Desktop).

• Node.js or Python runtime environment.

Installation

Instructions for installation

# Clone the repository
git clone https://github.com/tomtom-international/tomtom-mcp

# Navigate to directory
cd tomtom-mcp

# Install dependencies
npm install

# Configure API key
export TOMTOM_API_KEY="your-api-key-here"

# Start the server
npm start

Client configuration example

{
  "mcpServers": {
    "tomtom": {
      "command": "npx",
      "args": ["-y", "@tomtom/mcp-server"],
      "env": {
        "TOMTOM_API_KEY": "your-api-key-here"
      }
    }
  }
}

References

• GitHub repository: https://github.com/tomtom-international/tomtom-mcp

• TomTom MCP Server documentation: https://developer.tomtom.com/tomtom-mcp/documentation/overview

• MCP specification.: https://modelcontextprotocol.io

• TomTom Developer Portal: https://developer.tomtom.com