Geospatial tools for agents

Connect a client

Add Mapsource directly as a remote MCP server when your client supports Streamable HTTP and secret transport headers.

Loading MCP tools…

Configure the header using your client’s secret storage. Client-specific environment substitution differs; a literal $MAPSOURCE_API_KEY string is not automatically expanded by every client. Mapsource subscription authentication is a Bearer key, not an OAuth sign-in flow.

The MCP endpoint is https://api.mapsource.io/mcp. Agents calling REST directly use the same host, for example https://api.mapsource.io/interpreter; an /api prefix also works.

For stdio-first clients, use the official local adapter. It reads the key from the process environment, forwards calls to the hosted service over HTTPS, and discovers the live tool list when it connects.

npm i mapsource-mcp

{
  "mcpServers": {
    "mapsource": {
      "command": "npx",
      "args": ["-y", "mapsource-mcp"],
      "env": { "MAPSOURCE_API_KEY": "your-key-from-secret-storage" }
    }
  }
}

Keep credentials out of the MCP URL and client configuration files committed to source control.

TypeScript SDK example

Install @modelcontextprotocol/sdk. This Node.js example connects to the server, lists available tools, and requests service status.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const key = process.env.MAPSOURCE_API_KEY;
if (!key) throw new Error("Set MAPSOURCE_API_KEY securely");
const client = new Client({ name: "my-mapsource-client", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(
  new URL("https://mapsource.io/mcp"),
  { requestInit: { headers: { Authorization: "Bearer " + key } } }
);
try {
  await client.connect(transport);
  const tools = await client.listTools();
  console.log(tools.tools.map(tool => tool.name));
  const status = await client.callTool({ name: "service_status", arguments: {} });
  console.log(status.content);
} finally {
  await client.close();
}

Tools and inputs

Select an action with the operation argument. Use tools/list or the server card for tool input schemas. The API reference lists related REST endpoints and access requirements.

Direct tools are also available for individual queries:

Use local lookup for a search bar or routing destination picker. Provide the current map/GPS coordinates as a bias. Do not select a destination automatically when the response reports ambiguity.

await client.callTool({
  name: "geo_search",
  arguments: { operation: "lookup", q: "Starbucks", lat: 45.52, lon: -122.68, limit: 8 }
});

// Businesses reachable within 15 minutes on foot, ordered by travel time.
await client.callTool({
  name: "geo_search",
  arguments: {
    operation: "discover", category: "coffee",
    lat: 45.52, lon: -122.68, minutes: 15,
    costing: "pedestrian", rankBy: "travel_time", limit: 8
  }
});

Discovery combines the local OSM query engine, polygon filtering and navigation services. It can also consume an existing isochrone in region. Read regional limits and pagination before enumerating a large area.

Use lookup for new address, business and brand integrations; geocode retains the older provider-backed response format. Lookup and discovery are included in all subscription plans. They require a subscription key; paying for an Overpass query with x402 does not unlock search. See shared quota accounting for internal Overpass, isochrone and matrix calls.

await client.callTool({
  name: "geo_search",
  arguments: {
    operation: "nearby",
    lat: 47.6062, lon: -122.3321,
    category: "cafe", radius: 800, limit: 25
  }
});

Supported tools return large results as handles containing an ID, count, and bounding box. Pass the handle to subsequent operations or retrieve its payload when needed. See result handles for expiry and storage limits.

Results and quota

Use geo_data with operation: "status" to check subsystem availability and the OpenStreetMap dataset timestamp.

Check isError before processing a tool response. Direct Overpass queries return text content with response metadata in structuredContent. Set spatial filters and output limits, and allow for result handles in place of large inline responses.

MCP and REST requests share subscription limits. Read current totals with geo_data, operation: "usage", or GET /usage. Apply a per-task call budget and stop when the quota is exhausted.

x402 query payments

x402 supports per-query USDC payments on Base mainnet (eip155:8453) without a subscription. The returned payment requirement specifies the network, asset, recipient, and price. Check payment availability before submitting a paid request.

curl --include "https://api.mapsource.io/x402/interpreter" \
  -H "Content-Type: application/json" \
  --data '{"query":"[out:json][timeout:30];node(1);out;"}'

The initial REST response is HTTP 402 with PAYMENT-REQUIRED and Bazaar input/output metadata. A compatible client signs an approved payment and retries with PAYMENT-SIGNATURE. Successful settlement provides PAYMENT-RESPONSE. The paid REST route requires JSON Overpass output.

Save the transaction hash from the settlement receipt for payment support. A query payment does not create a subscription, issue an API key, or renew automatically. Anonymous MCP calls to overpass_query and find_features use the same payment flow; their receipts are returned in _meta["x402/payment-response"].

Authorize the network, amount, and total task budget before signing. An unpaid challenge does not charge the wallet. Check settlement status before retrying a signed payment.

If the agent has no compatible authorized wallet, direct the user to subscription signup and request the resulting API key through a secret or environment variable. Tiles and elevation require a subscription; query payment does not unlock them.

Examples and discovery

See the Mapsource geospatial MCP server overview and the OpenStreetMap place and feature search guide.

• Compact agent contract and full machine-readable guide.
• MCP server card, OpenAPI specification, and Markdown agent guide.
• TypeScript, Python, and map examples for amenities, footprints, basemaps, and elevation.