# Graphhopper — how to use (mcp.ai)

Connect your Graphhopper account and use 13 tools for developer tools straight from your AI agent. Connect with your own API key. GraphHopper Directions API provides enterprise-grade routing services, including route planning, optimization, geocoding, and more, for various vehicle types.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_graphhopper?ms=1787295780000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `graphhopper_cluster_post`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/graphhopper`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/graphhopper/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/graphhopper/cluster/post` — Solve capacity-constrained clustering problems by assigning customers to clusters while minimizing total travel distance. Useful for delivery zone planning, sales territory optimization, and workload 
  - body: { clusters?: object[], customers: object[], configuration: object }
- `POST https://api.mcp.ai/api/graphhopper/geocode/get` — Tool to perform forward or reverse geocoding. Use when converting between textual addresses and latitude/longitude coordinates.
  - body: { q?: string, key?: string, bbox?: string, zoom?: number, debug?: boolean, limit?: integer, point?: string, bounds?: string, locale?: string, radius?: number, osm_tag?: string[], reverse?: boolean, provider?: string, countrycode?: string, autocomplete?: boolean, location_bias_scale?: number }
- `POST https://api.mcp.ai/api/graphhopper/get/cluster/solution` — Tool to retrieve the solution of an asynchronous clustering job. Use when you have a job ID from a previous cluster calculation request and need to fetch the results.
  - body: { job_id: string }
- `POST https://api.mcp.ai/api/graphhopper/get/matrix` — Tool to compute a distance and/or time matrix using GET request with query parameters. Use for simpler matrix requests with query parameters instead of POST body.
  - body: { point?: string[], profile?: string, curbside?: string[], to_point?: string[], fail_fast?: boolean, out_array?: string[], from_point?: string[], point_hint?: string[], to_curbside?: string[], from_curbside?: string[], to_point_hint?: string[], from_point_hint?: string[], snap_prevention?: string[] }
- `POST https://api.mcp.ai/api/graphhopper/get/matrix/solution` — Tool to retrieve the result of an asynchronous matrix computation job. Use when you have a job ID from a previous matrix calculation request and need to check if it's finished and get the results.
  - body: { job_id: string }
- `POST https://api.mcp.ai/api/graphhopper/get/route` — Tool to calculate the best path connecting two or more points using simple GET request. Use when you need basic routing with query parameters.
  - body: { debug?: boolean, point: string[], locale?: string, details?: string[], heading?: integer[], profile?: string, curbside?: string[], optimize?: string, algorithm?: string, elevation?: boolean, ch.disable?: boolean, point_hint?: string[], calc_points?: boolean, instructions?: boolean, pass_through?: boolean, points_encoded?: boolean, heading_penalty?: integer, round_trip.seed?: integer, snap_prevention?: string[], round_trip.distance?: integer, alternative_route.max_paths?: integer, alternative_route.max_share_factor?: number, alternative_route.max_weight_factor?: number }
- `POST https://api.mcp.ai/api/graphhopper/isochrone/get` — Tool to compute isochrone polygons for a given point. Use when you need to determine areas reachable within time or distance constraints.
  - body: { point: string, buckets?: integer, profile: string, time_limit?: integer, reverse_flow?: boolean, distance_limit?: integer }
- `POST https://api.mcp.ai/api/graphhopper/matrix/post` — Tool to calculate distance, time, or weight matrices via POST. Use when you have multiple origins/destinations or a symmetric point set and need a single batch request.
  - body: { points?: number[][], profile: string, curbsides?: string[], fail_fast?: boolean, to_points?: number[][], out_arrays: string[], from_points?: number[][], point_hints?: string[], to_curbsides?: string[], from_curbsides?: string[], to_point_hints?: string[], from_point_hints?: string[], snap_preventions?: string[] }
- `POST https://api.mcp.ai/api/graphhopper/profiles/get` — Retrieve all custom routing profiles for your GraphHopper account. Custom profiles allow you to customize routing behavior (e.g., avoid certain roads, limit speeds, prefer certain road types). Use thi
- `POST https://api.mcp.ai/api/graphhopper/route/post` — Tool to calculate complex routes via POST /route. Use when you need advanced route planning with custom parameters.
  - body: { debug?: boolean, locale?: string, points: number[][], details?: string[], profile: string, headings?: integer[], optimize?: boolean, algorithm?: string, curbsides?: string[], elevation?: boolean, ch.disable?: boolean, round_trip?: object, calc_points?: boolean, point_hints?: string[], custom_model?: object, instructions?: boolean, pass_through?: boolean, points_encoded?: boolean, heading_penalty?: integer, snap_preventions?: string[], alternative_route?: object }
- `POST https://api.mcp.ai/api/graphhopper/submit/matrix/job` — Tool to submit a matrix computation job for asynchronous processing. Use for large matrices that exceed synchronous limits. Returns a job ID to retrieve results later.
  - body: { points?: number[][], profile: string, curbsides?: string[], fail_fast?: boolean, to_points?: number[][], out_arrays: string[], from_points?: number[][], point_hints?: string[], to_curbsides?: string[], from_curbsides?: string[], to_point_hints?: string[], from_point_hints?: string[], snap_preventions?: string[] }
- `POST https://api.mcp.ai/api/graphhopper/upload/gpx/file` — Map-match a GPX track using GraphHopper's Map Matching API. This tool takes GPS track points in GPX format and snaps them to the digital road network. It's useful for: - Cleaning noisy GPS data by ali
  - body: { locale?: string, profile?: string, elevation?: boolean, gpx_content: string, points_encoded?: boolean }
- `POST https://api.mcp.ai/api/graphhopper/vrp/post` — Tool to initiate VRP optimization. Use when you need to solve vehicle routing problems synchronously.
  - body: { services?: object[], vehicles: object[], algorithm?: object, relations?: object[], shipments?: object[], objectives?: object[], configuration?: object, cost_matrices?: object[], vehicle_types?: object[] }

## Example prompts
- "What can I do in Graphhopper?"
- "Show me a summary of my Graphhopper account"

## More
- Page: https://mcp.ai/graphhopper
- Agent spec (llms.txt): https://mcp.ai/graphhopper/llms.txt
- Postman collection: https://mcp.ai/graphhopper/postman.json