Connect your agent to ShowMeOnMap

1 · Get a key

Buy a credit pack (from $5 for 100 credits), then open the account menu → API keys → Create key. Copy the smo_live_… key — it is shown exactly once. Revoke any key from the same menu.

Every map your agents build spends your credits at web-app rates: 1 credit per standard map or mutation, 3 per agent-grade map; reads and exports are free. Failed requests are refunded automatically.

2 · Connect — hosted endpoint (recommended)

No install. Point any remote-MCP client at the endpoint with your key — Claude custom connectors, Cursor, Windsurf, Copilot Studio, Bedrock, and Google Gemini all accept this shape (and any newer client that speaks remote MCP):

{
  "mcpServers": {
    "showmeonmap": {
      "url": "https://showmeonmap.com/api/mcp",
      "headers": { "Authorization": "Bearer smo_live_YOUR_KEY" }
    }
  }
}

From the OpenAI Responses API / Agents SDK:

// OpenAI Responses API — remote MCP tool
{
  "model": "gpt-5",
  "tools": [{
    "type": "mcp",
    "server_label": "showmeonmap",
    "server_url": "https://showmeonmap.com/api/mcp",
    "headers": { "Authorization": "Bearer smo_live_YOUR_KEY" }
  }],
  "input": "Map earthquakes above magnitude 5 near Japan this month"
}

Or raw JSON-RPC over HTTP:

curl https://showmeonmap.com/api/mcp \
  -H 'Authorization: Bearer smo_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3 · Or run it locally (stdio)

For clients that spawn local MCP servers (Claude Desktop, Zed), use the npm package — same tools, same key:

{
  "mcpServers": {
    "showmeonmap": {
      "command": "npx",
      "args": ["-y", "@showmeonmap/mcp"],
      "env": {
        "SHOWMEONMAP_BASE_URL": "https://showmeonmap.com",
        "SHOWMEONMAP_API_KEY": "smo_live_YOUR_KEY"
      }
    }
  }
}

What your agent can do

build_map bootstraps a workspace from a natural-language query; mutate_map and 14 typed operations refine it (filter, restyle, camera, annotations, time windows); add_fusion_layer and correlate_layers run bivariate analysis; exports deliver CSV / GeoJSON / image links. Every response carries a shareable_url — a live map page your agent can hand straight to a human.

Prefer plain REST? Same key, same routes

The MCP tools are thin wrappers over a documented HTTP API — anything they can do, a plain script or backend can do directly with the same smo_live_… key. The full surface is specified in OpenAPI (openapi.yaml). Two calls cover most integrations:

# 1 credit — natural language in, full map plan out
curl https://showmeonmap.com/api/workspace/new \
  -H 'Authorization: Bearer smo_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"message": "earthquakes above magnitude 5 near Japan this month"}'
# → { "type": "visualization", "mapPlan": {…}, "workspace": {…}, … }

Refine with POST /api/workspace/mutate (send the returned workspace + an instruction, 1 credit), then share and export for free:

# Free — save it under a stable id, get a shareable page
curl https://showmeonmap.com/api/maps \
  -H 'Authorization: Bearer smo_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"id": "my-japan-quakes", "title": "Japan M5+ quakes",
       "query": "earthquakes above magnitude 5 near Japan this month",
       "blob": {"version": 1, "mapPlan": MAP_PLAN_FROM_STEP_1}, "isPublic": true}'
# → live page at https://showmeonmap.com/m/my-japan-quakes
# → layer data: POST /api/export/layer-data {"map_id","layer_id","format":"csv"}

Add "stream": true to the build call for a live text/event-stream of progress events (plan → fetch → analyze → render), ending in a final frame with the same JSON payload. Errors are typed: 401 AUTH_REQUIRED · 402 NO_CREDITS · 429 with Retry-After — throttled and failed requests never spend credits.

In the browser: WebMCP (no key needed)

showmeonmap.com also registers its tools in the page via WebMCP (document.modelContext). If you browse here with an agent-capable browser — ChatGPT's browser, or Chrome's origin trial — your agent can drive the live canvas directly: build_map, mutate_map, get_map_state, query_features, set_camera, zoom_to_layer, export_image, undo. Same vocabulary as the server MCP, but riding your own session: anonymous visitors get the standard 3 free maps/day, signed-in accounts spend the same 1 credit per map or mutation — no API key, and the human watches every change happen on the shared canvas.

Limits & notes

• 30 requests/min per key (429 with Retry-After past that; throttled requests never spend credits).
• Up to 10 active keys per account — mint one per agent so a misbehaving one can be revoked alone.
• The hosted endpoint is stateless streamable HTTP; send JSON-RPC via POST (no SSE stream).
• Some MCP hosts cap tool-result sizes (~150k chars on claude.ai) — very large layers may truncate; the shareable_url always carries the full map.
• Keys never expire; revocation is permanent and immediate.

Questions

See how ShowMeOnMap works and pricing. The MCP client package is open source (Apache-2.0): @showmeonmap/mcp.