npm package: @magiclane/mcp-server
Description: Magic Lane MCP server for geospatial tools
Author: Magic Lane International B.V.
Latest version: 1.1.1

# Magic Lane MCP Server

## Introduction

The **Magic Lane Model Context Protocol (MCP) Server** enables any AI agent or application to become a **geospatially intelligent assistant**, capable of acting as a reliable companion for pedestrians, cyclists, and drivers alike.

Built on top of **Magic Lane's advanced mapping and routing technology**, this TypeScript-based MCP server empowers AI agents to:

- Understand and process geospatial data,
- Interpret user intent in a spatial context,
- Deliver accurate, contextually relevant navigation guidance.

By leveraging **Magic Lane's global map data** and **real-time geospatial intelligence**, the MCP Server enables deeply personalized navigation and trip-planning experiences through core tools:

- **Intelligent Search** - Find addresses, points of interest (POIs), or coordinates with intelligent search capabilities and POI category filtering.

- **Smart Routing** - Generate optimized routes between multiple waypoints with support for various transport modes, route preferences, and dynamic POI integration.

- **Round Trip Planning** - Create circular routes that start and end at the same location, perfect for jogging routes, cycling loops, or delivery runs.

- **Reverse Geocoding** - Convert geographic coordinates into detailed address information including street name, city, state, country, and postal code.

- **Isochrone Analysis** - Calculate reachability polygons showing areas accessible within specific time or distance constraints.

- **Route Visualization** - Create visual map images of calculated routes, isochrones, and round trips for immediate geographical context and presentation.

- **Geofence Management** - Create, manage, and query geographic boundaries for asset monitoring, location-based alerts, and spatial analysis with support for polygons, circles, and rectangles.

The map functionalities can be visualized as high-quality map images through our new beta feature:

- **Static Map Rendering** - Generate custom map views with markers, bounding boxes, or location-centered areas without route calculation, complementing route visualization for routes, isochrones, and round trips.

Together, these capabilities enable AI agents to act as **true geospatial copilots** - understanding spatial context, anticipating user needs, and optimizing every journey with precision and ease.

**Transport Options:** The server supports both **stdio** (for MCP-native clients like Claude Desktop) and **HTTP** (for web applications, serverless deployments, and custom integrations).

![Magic Lane MCP Server Demo](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/examples/claude-demo.gif?raw=true)

## Getting Started

### Prerequisites

The **Magic Lane MCP Server** integrates seamlessly with any AI application or agent, providing access to geospatial data and navigation functionality. Before setup, ensure you have the following:

**System Requirements:**

1. **Node.js 22+** installed ([Download here](https://nodejs.org/))
2. **npm** (comes with Node.js)
3. A valid **Magic Lane API Key** (for access to map data)
4. An **MCP-compatible AI client**, such as:
   - [Claude Desktop](https://claude.ai/download)
   - [Cursor IDE](https://cursor.sh/)
   - **Visual Studio Code** with [GitHub Copilot](https://github.com/features/copilot)

**Verify Prerequisites:**

```bash
# Check Node.js version (should be 22+)
node --version

# Check npm version
npm --version
```

### Quick Start

For immediate testing, use npx to run the server without installation:

```bash
# Set your API key as environment variable
export MAGICLANE_API_KEY="your_api_key"

# Run the server directly
npx @magiclane/mcp-server
```

### API Key Setup

To obtain a Magic Lane API token, follow our [step-by-step guide](https://developer.magiclane.com/docs/guides/get-started). The detailed steps are:

1. **Create a Magic Lane Account**
   - Visit [developer.magiclane.com/api/register](https://developer.magiclane.com/api/register) and register for a free account.

2. **Generate an API Key**
   - Log in to your account
   - Navigate to the [Projects Dashboard](https://developer.magiclane.com/api/dashboard)
   - Follow the instructions to generate your unique API key, which will serve as your access token for the MCP Server

### Installation

To explore and integrate the MCP Server locally, follow these steps to install dependencies and build the project:

```bash
# Clone or navigate to the Magic Lane MCP Server directory
cd path/to/magiclane-mcp/mcp-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Verify the build was successful
ls dist/  # Should show map-server.esm.js and other compiled files
```

> **Note:** Ensure Node.js 22+ and npm are properly installed before running these commands.

### Running the Server

**Standard MCP Server (stdio transport):**

```bash
# Option 1: Using .env file (recommended)
cp .env.example .env
# Edit .env with your actual API key
npm start

# Option 2: Using Node's built-in env file support
node --env-file=.env dist/map-server.esm.js

# Option 3: Using environment variable directly
MAGICLANE_API_KEY=your_api_key npm start
```

**HTTP Server (for web and custom clients):**

```bash
# Development mode (with auto-reload)
npm run dev:http

# Production mode (after build)
npm run start:http
```

For complete HTTP server documentation including endpoints, JSON-RPC examples, and client integration, see the **[HTTP Server Setup Guide](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/http-server-setup.md)**.

### Configuration

Configure your MCP client to connect to the Magic Lane server. Follow the detailed setup guide for your specific AI client:

- **[Claude Desktop Setup Guide](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/claude-desktop-setup.md)** - Complete configuration instructions for Claude Desktop
- **[Cursor AI Setup Guide](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/cursor-setup.md)** - Step-by-step setup for Cursor IDE
- **[VS Code Setup Guide](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/vscode-setup.md)** - Integration guide for Visual Studio Code with GitHub Copilot

Each guide includes:

- Client-specific configuration file locations
- Multiple installation options (local build, NPM, Docker)
- Platform-specific instructions (Windows, macOS, Linux)

### Docker

Build and run the server using Docker:

```bash
# Build the Docker image
docker build -t magiclane-mcp-server .

# Run the container (pass API key via environment variable)
docker run --rm -e MAGICLANE_API_KEY=your_api_key magiclane-mcp-server

# Or use an env file
docker run --rm --env-file .env magiclane-mcp-server
```

**Environment Variables:**

| Variable            | Required | Description                                |
| ------------------- | -------- | ------------------------------------------ |
| `MAGICLANE_API_KEY` | Yes      | Your Magic Lane API key for authentication |

The container runs with `--enable-source-maps` for better stack traces in production.

---

## Available Tools

The **Magic Lane MCP Server** provides several integrated geospatial tools that enable AI systems to search, plan, analyze, and visualize routes and locations.

## 1. Location Search

The **Location Search Tool** uses the [Magic Lane Search REST API](https://developer.magiclane.com/docs/cloud-rest-api/guides/locations-search/search-api) to find:

- Coordinates, addresses, or administrative areas.
- Points of Interest (POIs) around a reference location (restaurants, gas stations, pharmacies, etc.).

#### Input Parameters

|        Parameter        |  Type   |   Default   | Description                                                                                                                                                                                                  |
| :---------------------: | :-----: | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|         `text`          | string  |      -      | Free-text query (e.g., city, address, or landmark)                                                                                                                                                           |
|    `poi_categories`     |  array  |    `[]`     | List of POI categories to filter results. Valid categories include `gas_stations`, `food&drink`, `medical_services`, `shopping`, `education`, `public_transport`, `sightseeing`, `entertainment`, and others |
|        `target`         |  array  | `addresses` | Defines the result categories to return ( `addresses`, `POIs`, or `both`).                                                                                                                                   |
|  `reference_location`   | string  |      -      | Coordinates or region used as search anchor                                                                                                                                                                  |
|       `language`        | string  |   `"en"`    | Response language (ISO 3166 code)                                                                                                                                                                            |
|      `max_results`      | number  |     `5`     | Maximum number of results                                                                                                                                                                                    |
| `estimate_house_number` | boolean |   `true`    | Interpolates missing house numbers                                                                                                                                                                           |

#### Example Prompts

- **Urban Exploration & Tourism**
  - "Search for authentic Italian restaurants in downtown Chicago within walking distance of Millennium Park."
  - "Where are the ATMs near Brandenburg Gate, Berlin?"

- **Business & Logistics**
  - "Locate the closest 'DHL Service Point' near Berlin Central Station."
  - "Find all Starbucks locations within 1km of our office at 1 Market Street, San Francisco."
  - "Where are the parking garages near Amsterdam Central Station?"

- **Real Estate & Property**
  - "Show all elementary schools near 456 Maple Avenue, Portland, Oregon with their exact distances from the property."
  - "Locate pharmacies, grocery stores, and public transport stops near the property at Baker Street 221B, London."

## 2. Routing Planner

The **Routing Planner Tool** generates optimized routes between multiple points using the [Magic Lane Routing REST API](https://developer.magiclane.com/docs/cloud-rest-api/guides/routing-navigation/routing-api) and the [Magic Lane Fleet Management Rest API](https://developer.magiclane.com/docs/cloud-rest-api/guides/fleet-management/introduction). This tool supports the following capabilities:

- Point-to-point and multi-stop routing (A -> B -> C).
- Inclusion of POIs (e.g., gas stations, restaurants).
- Advanced VRP optimization for multi-delivery routes.
- Traffic, restriction, and terrain considerations.
- Multilingual route instructions.

#### Input Parameters

|        Parameter         |  Type   |   Default   | Description                                                                                                                                                                                                                                               |
| :----------------------: | :-----: | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|       `transport`        | string  |   `"car"`   | Transport type (`car`, `lorry`, `truck`, `pedestrian`, `bike`, `public`)                                                                                                                                                                                  |
|          `type`          | string  | `"fastest"` | Optimization type (`fastest`, `shortest`, `economic`, `scenic`)                                                                                                                                                                                           |
|         `origin`         | string  |      -      | Start location (name or coordinates)                                                                                                                                                                                                                      |
|      `destination`       | string  |      -      | End location (name or coordinates)                                                                                                                                                                                                                        |
| `intermediate_waypoints` |  array  |    `[]`     | List of stops between start and end. Order determines route generation. Each waypoint defines specific preferences and constraints                                                                                                                        |
|         `avoid`          |  array  |    `[]`     | Elements to avoid (`highway`, `toll`, `ferry`, `unpaved`, `turnaround`, `traffic`, `roadblocks`)                                                                                                                                                          |
|        `vehicle`         | object  |   `null`    | Vehicle characteristics including dimensions, weight, fuel type, EV parameters and profile preference. See [Vehicle Specification](https://developer.magiclane.com/docs/cloud-rest-api/guides/routing-navigation/common_parameters/) for complete details |
|        `details`         | string  |  `"full"`   | Response detail level (`full`, `basic`)                                                                                                                                                                                                                   |
|    `number_of_routes`    | number  |     `1`     | Number of routes (1-3 car/bike; <= 11 public transport)                                                                                                                                                                                                   |
|     `fitness_factor`     | number  |    `0.5`    | Bike / pedestrian terrain preference (0-1)                                                                                                                                                                                                                |
|    `emergency_status`    | boolean |   `false`   | Enable emergency vehicle mode                                                                                                                                                                                                                             |
|        `language`        | string  |   `"en"`    | Output language                                                                                                                                                                                                                                           |

#### Intermediate Waypoint Structure

|       Parameter       |  Type  |        Default         | Description                                                                                                                                                      |
| :-------------------: | :----: | :--------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      `location`       | string |           -            | Location or address of the stop; can also specify a POI category                                                                                                 |
| `location_preference` | string | `"close to departure"` | Preferred placement of this stop along the route. Options: `close to destination`, `close to departure`, `midpoint of the route`, `static location`, `no matter` |
|  `maximum_deviation`  | number |         `500`          | Maximum allowed deviation (in meters)                                                                                                                            |

#### Example Prompts

- **International Travel & Tourism**
  - "Generate a scenic bike route from Vienna to Bratislava, avoiding highways."
  - "Plan a road trip from Munich to Venice with stops at Innsbruck and Bolzano, optimized for scenic views."

- **Public Transit & Commuting**
  - "Find a public transport route from London to Oxford with minimal transfers."
  - "What's the quickest way to get from JFK Airport to Manhattan using public transport?"

- **Multi-Stop Sightseeing & Events**
  - "Create a walking tour from the Colosseum to the Trevi Fountain, stopping at the Pantheon and a gelato shop."
  - "I'm at the Eiffel Tower and need to visit Notre-Dame, Louvre Museum, and return to my hotel near Gare du Nord. Plan the best route by car."

- **Emergency & Priority Routing**
  - "Find the fastest route from St. John Ambulance Station, Westminster to General Hospital, avoiding traffic and roadblocks."
  - "Calculate the quickest route for emergency services from Fire Station 23 to the reported incident at Pike Place Market."

- **Electric Vehicle Routing**
  - "I'm driving a Tesla Model 3 with 60% battery from San Francisco to Los Angeles. Find the optimal route with necessary charging stops, ensuring I arrive with at least 20% charge."
  - "Calculate a route for my electric van (80 kWh battery, 250km range) from Berlin to Prague with fast-charging stops along the way."

## 3. Isochrone Calculator

The **Isochrone Calculator Tool** provides spatial analysis to determine all areas reachable from a reference point within specific travel time or distance constraints using the using the [Magic Lane Isochrones REST API](https://developer.magiclane.com/docs/cloud-rest-api/guides/routing-navigation/isochrones-api). This enables AI systems to analyze accessibility zones, service coverage areas, and reachability studies.

**Key Features:**

- Calculate reachability polygons based on time or distance constraints
- Support for multiple transport modes (walking, cycling, driving, public transport)
- Departure location resolution through coordinates or geocoding
- Multi-range analysis for complex accessibility studies

#### Input Parameters

|    Parameter     |  Type  |   Default   | Description                                                                                      |
| :--------------: | :----: | :---------: | ------------------------------------------------------------------------------------------------ |
| `transport_mode` | string |   `"car"`   | Transport mode (`car`, `bike`, `pedestrian`)                                                     |
|  `routing_type`  | string | `"fastest"` | Routing type (`fastest`, `shortest`, `economic`, `scenic`)                                       |
|   `departure`    | string |      -      | Starting point location (name or coordinates)                                                    |
|     `ranges`     | array  |      -      | Range list (meters if routing type is `shortest`, seconds if routing type is `fastest`)          |
|     `avoid`      | array  |    `[]`     | Elements to avoid (`highway`, `toll`, `ferry`, `unpaved`, `turnaround`, `traffic`, `roadblocks`) |
|    `language`    | string |   `"en"`    | Result language (ISO 3166-1_3 or ISO 3166-1_2)                                                   |

#### Example Prompts

- "Where can I cycle to in 45 minutes from Amsterdam Central Station?"
- "Display all areas within a 10-minute walk from Atlantic Avenue-Barclays Center Station in Brooklyn."
- "Display the 1-hour driving catchment area from the proposed warehouse location in Frankfurt."

## 4. Round Trip Planner

The **Round Trip Planner Tool** generates circular routes that start and end at the same location. This tool is perfect for creating exploration routes, cycling loops, jogging paths, and delivery runs.

**Key Features:**

- Circular routes with guaranteed return to starting point
- Time-based or distance-based route generation
- Support for multiple transport modes (walking, cycling, driving)
- Terrain and hill skip preferences for cyclists
- Customizable route length and complexity

#### Input Parameters

|    Parameter     |  Type  |   Default   | Description                                                                                      |
| :--------------: | :----: | :---------: | ------------------------------------------------------------------------------------------------ |
| `transport_mode` | string |   `"car"`   | Transport mode (`car`, `bike`, `pedestrian`)                                                     |
|  `routing_type`  | string | `"fastest"` | Routing type (`fastest` or `shortest`)                                                           |
|   `departure`    | string |      -      | Starting point location (name or coordinates) - also the return destination                      |
|     `range`      | number |      -      | Route range (meters if routing type is `shortest`, seconds if routing type is `fastest`)         |
|     `avoid`      | array  |    `[]`     | Elements to avoid (`highway`, `toll`, `ferry`, `unpaved`, `turnaround`, `traffic`, `roadblocks`) |
|  `random_seed`   | number |     `0`     | Seed for route generation reproducibility                                                        |
|    `language`    | string |   `"en"`    | Result language (ISO 3166-1)                                                                     |

#### Example Prompts

- **Fitness & Recreation**
  - "Create a 10km jogging loop starting from Central Park."
  - "Design a 90-minute bike ride loop from Stephansplatz."
- **Tourism & Exploration**
  - "Generate a 45-minute walking loop from the Eiffel Tower."
  - "Plan a 2-hour walking loop starting from Times Square."

- **Cycling Routes**
  - "Create a 25km bike loop from Whistler Village, avoiding highways."
  - "Design a 1-hour cycling loop from Golden Gate Park using the shortest route."

## 5. Reverse Geocoding

The **Reverse Geocoding Tool** converts geographic coordinates or areas into detailed address information using the [Magic Lane Reverse Geocoding REST API](https://developer.magiclane.com/docs/cloud-rest-api/guides/locations-search/reverse-geocode-api). This tool provides comprehensive address components for various spatial queries.

**Key Features:**

- Point-to-address conversion for specific coordinates
- Search around a point, within an area, or along a path
- Returns multiple address results with distance ranking
- Includes administrative hierarchy (settlement, city, county, state, country)
- Identifies nearby points of interest

#### Input Parameters

| Parameter  |  Type  | Default | Description                                                                                                                                                                                                                                              |
| :--------: | :----: | :-----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|    `at`    | object |    -    | Specific coordinate point [longitude, latitude] for address lookup                                                                                                                                                                                       |
|    `in`    | object |    -    | Area definition using a rectangular area defined by `east`, `west`, `north`, `south` boundaries, circular area defined by `center` coordinates and `radius` in meters or a custom area defined by polyline string or coordinate array (minimum 3 points) |
|  `along`   | object |    -    | Path definition (encoded polyline or coordinates) with radius (in meters) to find addresses along                                                                                                                                                        |
|  `limit`   | number |   `5`   | Maximum number of results to return                                                                                                                                                                                                                      |
| `language` | string | `"en"`  | Result language (ISO 3166-1)                                                                                                                                                                                                                             |

#### Example Prompts

- "What's the address at coordinates 51.5074, -0.1278?"
- "Find all addresses within a 500-meter radius of the Brandenburg Gate."

## 6. Geofence Manager

The **Geofence Manager Tool** provides comprehensive geofence operations for defining and managing geographic boundaries, enabling location-based services and asset monitoring. This tool supports creating, retrieving, updating, deleting geofences, and checking if points fall within defined boundaries.

**Key Features:**

- Create geofences with polygon, circle, or rectangle geometries
- Query geofences by ID, within bounding boxes, or by proximity to a point
- Update geofence properties (name, keywords)
- Delete geofences by ID
- Check if specific coordinates fall inside geofences
- Support for custom metadata and tags

#### Operations & Parameters

**Create Operation** - Create one or more geofences with the following parameters:

|   Parameter    |  Type  | Default | Description                                                          |
| :------------: | :----: | :-----: | -------------------------------------------------------------------- |
|      `id`      | string |    -    | Custom identifier (auto-generated if not provided)                   |
|     `name`     | string |    -    | Human-readable name                                                  |
|   `keywords`   | array  |   []    | Tags for search and filtering                                        |
|  `properties`  | object |    -    | Additional custom metadata                                           |
| `geojson_type` | string |    -    | Geometry type: `polygon`, `circle`, or `rectangle`                   |
| `geojson_area` | object |    -    | Area definition (polygon coordinates, circle center/radius, or bbox) |

**Read Operation** - Retrieve one or more geofences with the following parameters:

|    Parameter     |  Type  | Default | Description                                                      |
| :--------------: | :----: | :-----: | ---------------------------------------------------------------- |
|  `geofence_ids`  | array  |    -    | Array of geofence IDs to retrieve                                |
|  `box_limited`   | object |    -    | Bounding box filter (north, south, east, west)                   |
| `proximity_area` | object |    -    | Search geofences near a point (reference_point, distance, limit) |

**Update Operation** - Modify properties of an existing geofence with the following parameters:

|   Parameter   |  Type  | Default | Description                                |
| :-----------: | :----: | :-----: | ------------------------------------------ |
| `geofence_id` | string |    -    | ID of geofence to update                   |
|    `name`     | string |    -    | Human-readable name to update the geofence |
|  `keywords`   | array  |   []    | Updated keywords/tags for geofence area    |

**Delete Operation** - Remove one or more geofences with the following parameters:

|   Parameter    | Type  | Default | Description                     |
| :------------: | :---: | :-----: | ------------------------------- |
| `geofence_ids` | array |    -    | Array of geofence IDs to delete |

**Check Point Operation** - Determine if coordinates fall within geofences with the following parameters:

|   Parameter    | Type  | Default | Description                                                 |
| :------------: | :---: | :-----: | ----------------------------------------------------------- |
| `geofence_ids` | array |    -    | Array of geofence IDs to check against                      |
|    `points`    | array |    -    | Array of locations to test (coordinates or location search) |

#### Example Prompts

- **Asset Monitoring & Tracking**
  - "Create a circular geofence with 500m radius around our warehouse at 123 Main Street, Chicago."
  - "Is the delivery vehicle at coordinates 40.7589, -73.9851 inside of Main Street zone geofence?"

- **Restricted Area Management**
  - "Create a rectangular 'construction-zone-1' geofence covering downtown Seattle bounded by these coordinates: north 47.6205, south 47.5990, east -122.3250, west -122.3450."
  - "Update the 'construction-zone-1' geofence to include 'temporary' and 'high-priority' keywords."

- **Service Area & Delivery Zones**
  - "Create three circular delivery zone geofences: 'berlin-warehouse-1' at coordinates 13.3777, 52.5163 with 2km radius, 'berlin-warehouse-2' at 13.4050, 52.5200 with 1.5km radius, and 'berlin-warehouse-3' at 13.3888, 52.5170 with 2.5km radius."
  - "Show me all geofences within 2km of Brandenburg Gate at coordinates 13.3777, 52.5163."
  - "Retrieve all geofences with IDs: 'zone-premium-01', 'zone-premium-02', and 'zone-premium-03' that are tagged with 'premium-service'."

- **Location-Based Alerts**
  - "Delete the temporary event geofences with IDs: 'summer-festival-2025-main', 'summer-festival-2025-parking', and 'summer-festival-2025-stage' now that the event is over."
  - "List all geofences within the bounding box covering Manhattan: north 40.8820, south 40.7006, east -73.9070, west -74.0479."
  - "Find all geofences near Times Square within 1000 meters and show their names and keywords."

## 7. Renderer

The **Renderer Tool** generates visual map images of calculated routes, isochrones, round trips, and static maps using the Magic Lane rendering service. This tool provides immediate geographical context by creating images that display geographic data overlaid on maps.

#### Key Features:

- Visual route/isochrone/round-trip representation as PNG (default), JPEG, or WebP format (modern, efficient)
- Automatic viewport calculation for optimal map framing
- Static map generation with custom bounding boxes or location-centered views
- Embedded in MCP client as base64-encoded images

#### Input Parameters

**Routing, Isochrone, and Round Trip:** Uses the same parameters as their respective calculation tools to render calculated routes with full path visualization, reachability polygons as colored areas, or circular routes with start/end point.

**Static Map:**

|     Parameter     |  Type  | Default | Description                                        |
| :---------------: | :----: | :-----: | -------------------------------------------------- |
|      `width`      | number |  `800`  | Image width in pixels (200-2000)                   |
|     `height`      | number |  `600`  | Image height in pixels (200-2000)                  |
|     `corners`     | array  |    -    | Bounding box as [minLon, minLat, maxLon, maxLat]   |
| `around_location` | object |    -    | Reference location with distance for centered view |

#### Example Prompts

- **Route representation**
  - I'm at 10 Downing Street, London - please show a driving route to St Paul's Cathedral.

![Route representation Overview](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/images/route.png?raw=true)

- **Round Trip representation**
  - Visualize a 5.5km jogging route starting from the Rijksmuseum in Amsterdam.

![Round trip representation Overview](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/images/round-trip.png?raw=true)

- **Isochrone representation**
  - Please display a map of Paris with a 15-minute walking isochrone.

![Isochrone representation Overview](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/images/isochrone.png?raw=true)

- **Static Map representation**
  - Display a wide view of Miami, including beach and the Art Deco Historic District.

![Static map representation Overview](https://github.com/magiclane/magiclane-mcp-server/blob/HEAD/docs/images/static-map.png?raw=true)

---

## Troubleshooting

### Common Issues

#### Server Won't Start

```bash
# Check if Node.js version is 22+
node --version

# Verify API key is set
echo $MAGICLANE_API_KEY

# Check for build errors
npm run build
```

#### API Key Issues

- Ensure your API key is valid and active in the [Magic Lane Dashboard](https://developer.magiclane.com/api/dashboard)
- Verify the environment variable is correctly set: `MAGICLANE_API_KEY=your_key`
- Check for extra spaces or quotes in the API key

#### Connection Problems

- Verify your MCP client configuration matches the server path
- Ensure the server is running before connecting the client
- Check firewall settings if using remote connections

#### Rate Limiting

- Magic Lane API has rate limits; check your dashboard for current usage
- Implement request caching for frequently accessed routes
- Consider upgrading your API plan if limits are exceeded

### Common Error Messages

- **Unauthorized access (401)**: Invalid API key. Check your configuration.
- **No results found (404)**: The location could not be found. Try a different query.
- **Too many requests (429)**: Rate limit exceeded. Check your usage dashboard.
- **Bad request (400)**: Invalid parameters. Check your input format.

## Privacy Policy

Magic Lane is committed to protecting your privacy and handling your data responsibly. For complete privacy information, see our full privacy policy: [https://www.magiclane.com/web/terms-and-conditions#privacy](https://www.magiclane.com/web/terms-and-conditions#privacy)

### Data Collection

- **Query data**: Location search terms, route origins/destinations, and coordinates submitted through the MCP server are transmitted to Magic Lane's API for processing. They are **not stored or logged** by Magic Lane after the response is delivered.
- **API key**: Your API key is transmitted with every request solely for authentication and rate limiting. It is never shared with third parties.
- **No user profiling**: Magic Lane does not build user profiles, track usage patterns across sessions, or correlate individual requests.

### How Data Is Used

- All requests are processed in real-time to generate the requested geospatial response (route, search result, isochrone, etc.).
- Processed data is immediately discarded after the response is delivered.
- Map rendering is performed dynamically; generated images are not retained after transmission.

### Data Storage & Retention

- Magic Lane does not persistently store the content of routing requests, location queries, search parameters, or reverse geocode inputs.
- No session data or request history is retained on Magic Lane servers.

### Third-Party Data

- Magic Lane uses OpenStreetMap data and other publicly available geographic datasets
- No personal or proprietary location data is shared with third parties
- Traffic and routing data is aggregated and anonymized at the source

For detailed information, review our [Terms of Service](https://www.magiclane.com/web/terms-and-conditions). and [Privacy Policy](https://www.magiclane.com/web/terms-and-conditions#privacy).

---

## Support

- **Documentation**: [developer.magiclane.com/docs](https://developer.magiclane.com/docs)
- **API Dashboard**: [developer.magiclane.com/api/dashboard](https://developer.magiclane.com/api/dashboard)
- **GitHub Issues**: [github.com/magiclane/magiclane-mcp-server/issues](https://github.com/magiclane/magiclane-mcp-server/issues)
- **Developer Portal Support**: Contact support through the developer portal