MCP connector

mapf for AI agents

mapf is live ground truth on where to go right now, for you and the AI agents choosing for you. Its MCP server lets your assistant search the live map and answer with the places that are open and alive at the hour you mean.

01What it does

The server gives your assistant two tools. Both are read-only: they look at the map and never book, buy or change anything.

• search_places takes one input, query: what to look for and where, in the user’s own words. It returns ranked places, each with its name, category, a live score from 0 to 100 for the hour you asked about, whether it is open, today’s hours, its position on the map, a cover photo and a link to mapf. The score is recent form: how well a place has been doing lately, weighted to that hour. It is not a crowd count and not a review rating. In ChatGPT and Claude the answer also renders as a live map card.
• list_cities lists the cities mapf covers, with the neighbourhoods in each and a link to every city’s live page.

It speaks MCP over Streamable HTTP: JSON-RPC 2.0 by POST, protocol versions 2024-11-05 through 2026-07-28. Clients that still open a legacy session with initialize are supported too.

02Choose an endpoint

The same map sits behind three addresses. They differ in who is asking and how the searches are counted.

https://mapf.ai/mcp Free, no sign-in

• 5 searches a day
• 5 places per answer

https://mapf.ai/mcp/me Your mapf account

The same tools, linked to your account. The first time you add it, your assistant asks you to sign in to mapf (OAuth 2.1). With mapf Go ($4.99 a month, and included with venue-owner plans):

• 100 searches a day, and up to 500 in any seven days
• 10 places per answer
• The live map at any hour you ask about, not only now

Venue-owner Pro and Max plans get 200 and 400 searches a day. A linked account without a plan gets 30 searches a day (up to 150 in any seven days) and 5 places per answer, counted for you rather than for your network.

https://mapf.ai/mcp/agent Autonomous agents, pay per search

• $0.01 per search, paid in USDC on Base over x402
• Up to 20 places per answer, no account
• New wallets start at 100 searches a day, rising to 500 a day after $5 of settled payments
• list_cities is free

03Set it up

Every app puts its connector settings somewhere slightly different, and those menus change. The part that matters is always the same: the server URL. Use https://mapf.ai/mcp to start, or https://mapf.ai/mcp/me to use your mapf account.

ChatGPT

In ChatGPT’s connector or apps settings, add a custom connector (turn on developer mode first if your plan asks for it) and give it this URL:

https://mapf.ai/mcp

When you reach the free limit, ChatGPT offers to link your mapf account so you can keep going.

Claude (web, desktop and mobile)

In Claude’s connector settings, add a custom connector with the free URL, or with the account URL if you want your mapf account behind it. Claude asks you to sign in to mapf when you add the second one.

https://mapf.ai/mcp
https://mapf.ai/mcp/me

Gemini (web and mobile)

Custom apps are added on the web at gemini.google.com: Settings, then Connected Apps, then Add a custom app under Custom apps. Give it the account URL, sign in to mapf when Gemini sends you there, and the app then shows up in the Gemini mobile app on the same Google account too. In a chat, type @ to pick mapf.

https://mapf.ai/mcp/me

Google offers custom apps to personal Google accounts in the US, in English, with Keep Activity on. Your account matters more here than elsewhere: without one, everyone using Gemini shares Google’s addresses, so the free daily searches can run out early.

Grok (grok.com)

Go to grok.com/connectors, choose New Connector, then Custom, and give it the account URL. Grok sends you to mapf to sign in and approve; there is no client ID or secret to fill in, because Grok registers itself.

https://mapf.ai/mcp/me

Grok may keep custom connectors to its paid plans.

Grok Build

grok mcp add --transport http mapf https://mapf.ai/mcp

Swap in https://mapf.ai/mcp/me to use your account: Grok Build opens your browser to sign in the first time. grok mcp doctor mapf checks the connection.

Grok Bot

Ask the bot in chat:

Add a custom MCP server called mapf at https://mapf.ai/mcp/me

It posts a connect card; open it, sign in to mapf and approve.

Claude Code

claude mcp add --transport http mapf https://mapf.ai/mcp

Swap in https://mapf.ai/mcp/me to use your account.

Cursor

In ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mapf": { "url": "https://mapf.ai/mcp" }
  }
}

VS Code (Copilot agent mode)

In .vscode/mcp.json:

{
  "servers": {
    "mapf": { "type": "http", "url": "https://mapf.ai/mcp" }
  }
}

Gemini CLI

In ~/.gemini/settings.json:

{
  "mcpServers": {
    "mapf": { "httpUrl": "https://mapf.ai/mcp" }
  }
}

Other assistants

Any other client that supports remote MCP servers over HTTP: point it at https://mapf.ai/mcp. To be plain about it, some consumer apps do not yet let you add your own connectors. If yours has no place for a server URL, it cannot use mapf yet.

OpenAI Responses API

"tools": [
  {
    "type": "mcp",
    "server_label": "mapf",
    "server_url": "https://mapf.ai/mcp",
    "require_approval": "never"
  }
]

Anthropic Messages API (MCP connector, beta)

"mcp_servers": [
  { "type": "url", "url": "https://mapf.ai/mcp", "name": "mapf" }
],
"tools": [
  { "type": "mcp_toolset", "mcp_server_name": "mapf" }
]

Send the request with the MCP connector beta header; see Anthropic’s MCP connector docs for the current one, since the beta has changed shape before. To use your account, set the URL to https://mapf.ai/mcp/me and add "authorization_token" to the server entry, carrying an OAuth access token for your mapf account.

Raw JSON-RPC, with curl

Useful for testing, or for wiring mapf into your own client. First, the handshake:

curl https://mapf.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Then a search:

curl https://mapf.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_places","arguments":{"query":"cocktail bars open late in Soho, London"}}}'

The handshake answer carries an Mcp-Session-Id header. If your client keeps sessions, send it back on later calls.

04Paying per search (x402)

The agent endpoint is for software acting on its own, with a wallet rather than an account. Any x402-capable client library handles the steps below for you; here is what happens underneath.

1. Call tools/call for search_places on https://mapf.ai/mcp/agent with no payment. The result is a PaymentRequired object: it is marked isError, and its structuredContent is the x402 challenge. It asks for scheme exact on network eip155:8453 (Base), asset USDC, amount 10000 (that is $0.01), paid to the payTo address it names.
2. Sign an EIP-3009 transferWithAuthorization for exactly that amount, valid for no more than 2 minutes.
3. Retry the same call with the payment in params._meta["x402/payment"], or in the PAYMENT-SIGNATURE HTTP header. x402 v2 only: X-PAYMENT is not read, and a v1 payload is refused.
4. The answer comes back with its receipt in _meta["x402/payment-response"] and in the PAYMENT-RESPONSE header.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": { "query": "rooftop bars in Melbourne tonight at 10pm", "rows": 20 },
    "_meta": { "x402/payment": { "...": "your signed payment payload" } }
  }
}

Lost the response? Present the same payment again, for the same query, within 10 minutes and you get the answer again, up to 3 times. You are never charged twice.

05Asking good questions

Write the query the way you would ask a friend who knows the city:

• “quiet cafes to work from in Canggu right now”
• “rooftop bars in Melbourne tonight at 10pm”
• “cocktail bars open late in Soho, London”
• “late-night dim sum in Mong Kok, Hong Kong”
• “brunch in Surry Hills, Sydney on Saturday at 11am”
• “live music in Williamsburg, New York tonight”

A few things help:

• Name the city or the neighbourhood. A neighbourhood name on its own can be ambiguous (Melbourne and Sydney both have a CBD), and then the answer asks which city you mean.
• Say the time if it isn’t now. “Tonight”, “Friday 9pm” and the like are read in the city’s own local time.
• One question per call. Two cities or two kinds of place make two searches.

Not sure a city is covered? Ask list_cities, or see every city at mapf.ai/live.

06Limits and fair use

• Daily limits reset at midnight UTC. A linked account can also search at most five days’ worth in any seven days: 150 searches without a plan, 500 with mapf Go, 1,000 with Pro and 2,000 with Max.
• Automated bulk extraction, scraping, or using mapf’s data to build a competing dataset is not allowed, and is blocked.
• Heavy automated use belongs on the paid agent endpoint, which is built for it.

07Privacy

For each call, the connector receives:

• the text of the query;
• the anonymous user id your assistant’s host sends, if it sends one;
• your network address, which is how the free limits are counted.

We never sell any of it. The full picture, including how long things are kept, is in the privacy policy.

08Questions