Build a MapQuest MCP Server for Agentic Geocoding, Routing & Maps

On August 5, 2026, MapQuest opened its thirty-year-old location platform to AI agents, launching MapQuest MCP, a hosted Model Context Protocol (MCP) server that exposes geocoding, routing, and mapping directly to any MCP-compatible agent. "Location is one of the first things developers reach for when they build an agent, and until now it meant reading API docs and writing code," said Doug Berger, MapQuest General Manager. To make the launch impossible to ignore, MapQuest opened a shared pool of 1 billion transactions that developers can consume for free while the community pool lasts. An agent can discover the MapQuest location tools automatically, authenticate with an API key, and start calling them in minutes from Claude, Cursor, Codex, or ChatGPT — no MapQuest-specific SDK to learn. This guide builds a production-grade Python FastMCP server, location-mcp, that wraps geocoding, reverse geocoding, routing, multi-stop optimization, and static maps into clean typed agent tools, then wires it into Claude Desktop and Cursor with inputSchema definitions, API-key security, rate limiting, and caching. As you map out your own agent tool surfaces and location endpoints, browse the MCP directory first and keep this build in context.

Why build your own gateway when MapQuest ships one?

The hosted Remote server is the fastest possible on-ramp — a five-minute setup, zero infrastructure, and the full Location Intelligence Suite including search and traffic. But a custom FastMCP gateway is the right call when any of these apply:

• A narrower, audited surface. The hosted endpoint exposes the full suite. A custom server exposes exactly the six tools your agents are approved to touch, which makes prompt-injection containment and security review tractable.
• Combined workflows in one call. A single directions_route call that geocodes both endpoints first, or a geocode cache that serves the same address across ten agents, is painful to orchestrate against a shared remote server.
• Cost control inside the free pool. With 1 billion transactions shared across the community, a fast read-your-own-writes geocode and route cache plus per-agent rate limits decides whether your dispatch agent sips the pool or drains it.
• Per-agent keys and revocation. A gateway issues one key per agent or tenant, so decommissioning a rogue agent means revoking a single key instead of rotating one shared credential.
• Composable agent patterns. The gateway composes with retrieval, approval, and notification steps the same way any other agent workflow on your platform does.

The tool surface and architecture

The gateway exposes six tools against the MapQuest REST APIs, all speaking JSON:

Each tool is a thin, cached, rate-limited call to the MapQuest API, so the agent surface you expose never becomes a new source of truth — it stays a governed view over the location platform.

Step 1: Scaffold the Python FastMCP server

mkdir location-mcp && cd location-mcp
python -m venv .venv && source .venv/bin/activate
pip install "fastmcp[cli]" requests

# server.py
import os
import time
import json
import threading
import hashlib

import requests
from fastmcp import FastMCP

KEY = os.environ["MAPQUEST_API_KEY"]
BASE = "https://www.mapquestapi.com"

mcp = FastMCP("location-mcp", instructions=(
    "Location tools for geocoding, routing, and maps. "
    "Cache hits are frequent; prefer structured coordinates over free text."
))

# --- token bucket rate limiter (20 req/s per agent) ---
_bucket = {"tokens": 20.0, "last": time.monotonic()}
_lock = threading.Lock()

def _limited():
    with _lock:
        now = time.monotonic()
        _bucket["tokens"] = min(20.0, _bucket["tokens"] + (now - _bucket["last"]) * 20.0)
        _bucket["last"] = now
        if _bucket["tokens"] < 1.0:
            return False
        _bucket["tokens"] -= 1.0
        return True

# --- TTL cache keyed by normalized payload ---
_cache = {}

def _cached(url, params, ttl=300):
    key = hashlib.sha256(f"{url}|{json.dumps(params, sort_keys=True)}".encode()).hexdigest()
    hit = _cache.get(key)
    if hit and hit["ts"] > time.time() - ttl:
        return hit["data"]
    if not _limited():
        return {"error": "rate_limit_exceeded", "detail": "retry in 60s"}
    r = requests.get(url, params={**params, "key": KEY}, timeout=10)
    r.raise_for_status()
    data = r.json()
    _cache[key] = {"ts": time.time(), "data": data}
    return data

@mcp.tool()
def geocode(address: str) -> str:
    """Convert an address or place name into precise coordinates."""
    return json.dumps(_cached(f"{BASE}/geocoding/v1/address", {"location": address, "maxResults": 1}))

@mcp.tool()
def reverse_geocode(latitude: float, longitude: float) -> str:
    """Reverse-geocode coordinates into a street address and place."""
    return json.dumps(_cached(f"{BASE}/geocoding/v1/reverse", {"location": f"{latitude},{longitude}"}))

@mcp.tool()
def directions_route(from_location: str, to_location: str, route_type: str = "fastest") -> str:
    """Plan a turn-by-turn route between two locations (addresses or lat,lng)."""
    return json.dumps(_cached(
        f"{BASE}/directions/v2/route",
        {"from": from_location, "to": to_location, "routeType": route_type, "unit": "k"}))

@mcp.tool()
def optimize_route(locations: list[str]) -> str:
    """Sequence a multi-stop route in optimal delivery order."""
    return json.dumps(_cached(
        f"{BASE}/directions/v2/optimizedroute",
        {"locations": locations}))

@mcp.tool()
def static_map(locations: list[str], size: str = "600,400") -> str:
    """Return a map image URL marking the given locations at the given size."""
    return _cached(f"{BASE}/staticmap/v5/map", {"locations": ",".join(locations), "size": size, "format": "png"})

@mcp.tool()
def place_search_nearby(location: str, radius_miles: int = 2, category: str = "") -> str:
    """Search places near a location, optionally filtered by category keyword."""
    return json.dumps(_cached(f"{BASE}/search/v4/nearby", {"origin": location, "radius": radius_miles, "key": KEY, "limit": 10}, ttl=60))

if __name__ == "__main__":
    mcp.run()

Run the server with python server.py and it speaks MCP over stdio to whichever client you wire next.

Step 2: inputSchema definitions published to agents

FastMCP derives JSON Schema from Python type hints, but it helps to pin the contract the agent sees. Here are the schemas the gateway publishes for the three tools an agent will burn most:

{
  "geocode": {
    "type": "object",
    "properties": {
      "address": { "type": "string", "description": "Street address, city, or place name to geocode" }
    },
    "required": ["address"]
  },
  "directions_route": {
    "type": "object",
    "properties": {
      "from_location": { "type": "string", "description": "Origin address or lat,lng" },
      "to_location": { "type": "string", "description": "Destination address or lat,lng" },
      "route_type": { "type": "string", "enum": ["fastest", "shortest", "pedestrian"], "default": "fastest" }
    },
    "required": ["from_location", "to_location"]
  },
  "optimize_route": {
    "type": "object",
    "properties": {
      "locations": { "type": "array", "items": { "type": "string" }, "description": "All stops including origin; the server returns the optimal order" }
    },
    "required": ["locations"]
  }
}

Descriptions matter ten times more in agent-facing schemas than in human API docs — the model chooses a tool off the description alone, so say what the tool returns and the units (kilometers, degrees) in every description string.

Step 3: Wire into Claude Desktop and Cursor

The custom gateway is a local stdio server, so it goes in claude_desktop_config.json (macOS) or the Cursor mcp.json:

{
  "mcpServers": {
    "location-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/location-mcp/server.py"],
      "env": {
        "MAPQUEST_API_KEY": "your-key-here"
      }
    }
  }
}

The hosted endpoint needs no code and is added as a remote server instead — same shape, transport swap:

{
  "mcpServers": {
    "mapquest": {
      "type": "http",
      "url": "https://www.mapquestapi.com/mcp"
    }
  }
}

From the Claude Code CLI this is one command: claude mcp add --transport http mapquest https://www.mapquestapi.com/mcp, then claude mcp login mapquest to authorize. After connecting, ask "What MCP tools do you have available?" to confirm the tools list.

API-key security, rate limits, and caching

• Key custody. The key is read from MAPQUEST_API_KEY at startup, never from source control. In production, inject it from your secret manager or an OS keychain instead of the JSON config, and rotate it on a schedule.
• One key per agent. Create a MapQuest key per agent or tenant. When an agent is retired, disable that key — every other agent keeps working. Audit key usage in the MapQuest dashboard per key, not per account.
• Rate limiting. The gateway's token bucket caps each agent at 20 requests per second. Raise it per agent with a distinct key so one runaway loop cannot starve a dispatch fleet.
• Caching. Geocodes and routes are deterministic: key the cache on normalized input with a short TTL so repeated queries within a delivery shift are served instantly and almost free. The place_search_nearby cache TTL is short (60s) so results stay fresh.
• Free-pool hygiene. Track consumed transactions from the pool against the Account API usage endpoint and surface a budget tool to the agent, so it can stop asking for new routes when the pool is nearly exhausted. That single piece of agent-visible economics is what turns a promotion into a production commitment.
• Prompt-injection guard. Treat coordinates and category strings as untrusted input; never let a tool argument silently bypass the allowlist. Pair the gateway with the same Model Armor-style screening you apply to your other production agent surfaces.

Use cases in the agentic world

• Last-mile logistics agents. A dispatch agent watches completed orders, calls geocode on each address, then optimize_route to re-sequence the driver's stops whenever a new delivery lands mid-shift.
• Delivery routing copilots. A customer-support agent answers "when will my package arrive?" by running directions_route with live traffic and returning the ETA range instead of a hub-canned reply.
• Store locator chatbots. A retail assistant takes "where is the nearest store that sells X?" as natural language, calls place_search_nearby, and renders the result through static_map directly in the chat card.
• Fleet telemetry dashboards. An operations agent aggregates reverse_geocode events from raw GPS pings and flags drivers who have gone off-route, feeding the exception list straight back into your workflow engine.

Testing the server end to end

python -m fastmcp inspect "$(pwd)/server.py"

> geocode("1 Infinite Loop, Cupertino, CA 95014")
  → lat: 37.331741, lng: -122.030333, quality: POINT, confidence: 1.0

> directions_route("Mountain View, CA", "San Francisco, CA", "fastest")
  → distance_km: 68.4, time_minutes: 72, legs: 3

> optimize_route(["Los Angeles, CA", "San Diego, CA", "Irvine, CA", "Long Beach, CA"])
  → optimal_order: ["Los Angeles, CA", "Irvine, CA", "Long Beach, CA", "San Diego, CA"]

Then repeat the same prompt in Claude Desktop with the server attached: the second geocode call should return from cache in single-digit milliseconds — proof the gateway, not the host, is doing the work.

Frequently Asked Questions

When did MapQuest launch its MCP server and what does it expose?

MapQuest launched the hosted MapQuest MCP server on August 5, 2026. It exposes the MapQuest location platform over Model Context Protocol: geocoding and reverse geocoding, turn-by-turn and multi-stop routing, and map image rendering, all auto-discoverable by MCP-compatible agents such as Claude, Cursor, Codex, and ChatGPT.

What is the 1 billion free transaction pool?

To celebrate the launch, MapQuest opened a shared pool of 1 billion transactions that developers can consume for free while the community pool lasts. Every geocode, route, or map request made through the MCP server draws from it, which makes it practical to prototype and ship location features without immediate cost concerns.

Should I use the hosted MapQuest endpoint or build my own server?

Use the hosted endpoint at mapquestapi.com for a five-minute start and full featured coverage. Build a custom FastMCP gateway when you need a narrower approved tool surface, combined geocode-then-route workflows in a single call, request caching to stretch quota, per-agent keys and rate limits, or human-in-the-loop dispatch approval.

How do I secure a MapQuest MCP gateway against quota abuse?

Store keys in environment variables or a secret manager, issue one key per agent or tenant so they can be revoked individually, apply a token-bucket rate limiter per agent, cache successful geocode and route responses keyed by normalized input, and deny-list calls when the free pool or your plan cap is exceeded.

Which tools should a production MapQuest MCP server expose?

A conservative production surface is geocode, reverse_geocode, directions_route, optimize_route for multi-stop delivery sequencing, static_map for embedded map images, and place_search_nearby for store locator lookups. Everything else, especially bulk batch geocoding, should stay behind an approval gate.

Closing thoughts

MapQuest's August launch removed the last friction between an agent asking "where?" and an agent acting on it, and the 1 billion free-transaction pool gives every team a risk-free window to ship location-native features. Production use still demands the boring engineering around the API — vaulted keys, rate limits, caches, and agent-scoped revocation. Build that ring now and your dispatch, routing, and locator agents will keep finding their way long after the promotion ends. Track more builds like this one in the MCP directory and keep an eye on AI news as more mapping platforms follow MapQuest's lead.