WinSurf Integration Guide

This guide explains how to configure WinSurf to use the TomTom MCP Server for location-based queries.

Prerequisites

• WinSurf installed
• Node.js 22+ (For STDIO)
• Docker Setup Required (For HTTP)
• A valid TomTom API key

Setup

1. Add the below configuration to your ~/.codeium/windsurf/mcp_config.json file in the WindSurf directory:

   Copy{ "mcpServers": { "tomtom-mcp": { "command": "npx", "args": ["-y","@tomtom-org/tomtom-mcp@latest"], "env": { "TOMTOM_API_KEY": "<your_API_KEY>" } } } }

   1{
   2  "mcpServers": {
   3     "tomtom-mcp": {
   4        "command": "npx",
   5        "args": ["-y","@tomtom-org/tomtom-mcp@latest"],
   6        "env": {
   7         "TOMTOM_API_KEY": "<your_API_KEY>"
   8        }
   9     }
   10  }
   11}

Alternative Setup: HTTP Mode

You can also run TomTom MCP in HTTP mode separately and connect to it from WinSurf:

1. Run TomTom MCP in HTTP mode using one of these methods:

   Using Docker

   Copy# Run using Docker docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest # Or with Docker Compose (after cloning the repository) docker compose up

   1# Run using Docker
   2docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest
   3
   4# Or with Docker Compose (after cloning the repository)
   5docker compose up

2. Configure WinSurf to connect to the HTTP server: Add the below configuration in /.codeium/windsurf/mcp_config.json:

   Copy{ "servers": { "tomtom-mcp": { "url": "http://localhost:3000/mcp", "headers": { "tomtom-api-key": "your_api_key_here" } } } }

   1{
   2  "servers": {
   3    "tomtom-mcp": {
   4      "url": "http://localhost:3000/mcp",
   5      "headers": {
   6        "tomtom-api-key": "your_api_key_here"
   7      }
   8    }
   9  }
   10}

This approach has several advantages:

• Separates the MCP server from VS Code, allowing you to restart either independently
• Useful when using the Docker image to avoid native dependency issues
• Enables sharing one MCP server instance across multiple tools/applications

Test It

Use WinSurf's integration features to query the MCP server for map, routing, or search data.

Troubleshooting

• Ensure TOMTOM_API_KEY is valid and active
• Check that the MCP server is running
• Review WinSurf logs for connection issues