# VS Code Integration Guide

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

## Prerequisites

- VS Code installed with Copilot
- Node.js 22+ (For STDIO)
- Docker Setup Required (For HTTP)
- A valid [TomTom API key](https://developer.tomtom.com/)

## Setup

1. Add the below config in `.vscode/settings.json`:
    ```json
    {
      "servers": {
         "tomtom-mcp": {
            "command": "npx",
            "args": ["-y", "@tomtom-org/tomtom-mcp@latest"],
            "env": {
              "TOMTOM_API_KEY": "<your_API_KEY>"
            }
         }
      }
    }
    ```

> **Tip:** To use the TomTom Orbis Maps backend (which includes additional tools like EV routing, search along route, and data visualization), add `"MAPS": "tomtom-orbis-maps"` to the `env` block above. See [Available Tools](../README.md#tomtom-orbis-maps-optional-backend) for details.

## Alternative Setup: HTTP Mode

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

1. **Run TomTom Maps MCP in HTTP mode**:

   **Using Docker**
   ```bash
   # Run using Docker
   docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-maps-mcp:latest

   # To use TomTom Orbis Maps backend instead:
   docker run -p 3000:3000 -e MAPS=tomtom-orbis-maps ghcr.io/tomtom-international/tomtom-maps-mcp:latest

   # Or with Docker Compose (after cloning the repository)
   docker compose up
   ```

2. **Configure VS Code to connect to the HTTP server**:
   Add the below configuration in `.vscode/settings.json`:
   ```json
   {
     "servers": {
       "tomtom-mcp": {
         "url": "http://localhost:3000/mcp",
         "headers": {
           "tomtom-api-key": "<your_API_KEY>",
           "tomtom-maps-backend": "tomtom-maps"
         }
       }
     }
   }
   ```

   > **Tip:** Set the `tomtom-maps-backend` header to `tomtom-orbis-maps` to use the Orbis Maps backend (which includes additional tools like EV routing, search along route, and data visualization). This header is only used when the server is started without the `MAPS` env var (dual-backend mode).

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

3. You can see the TomTom Maps MCP tools in Copilot tools menu.

![img.png](../images/vscode_tools.png)


## Troubleshooting

- Ensure **TOMTOM_API_KEY** is valid and active
- Check that the MCP server is running
- Review logs for connection errors
- For HTTP mode, verify your connection URL and port are correct
- When using Docker, make sure the container is running with `docker ps`