Connect

Integration guide

How to call places.agent-mate.ai. The agent id is places-agent. Callers send a caller API key. Map-vendor keys stay on the server.

1. Agent capabilities

Callers get these tools. HTTP and MCP share the same JSON unless marked HTTP only. Callers pass providers[] as GOOGLE_MAPS and/or AMAP. Search and details cards include sources[].

Capabilities	Channel	Description
`search_restaurants`	HTTP and MCP	Find restaurants near coordinates or an address. Optional cuisine, keyword, and open now. Empty matches return errors.empty_results.
`search_places`	HTTP and MCP	Find non-restaurant places (museums, parks, attractions). Same card shape and vendor contract as restaurant search.
`get_place_details`	HTTP and MCP	Load one place by provider native_id. Missing places return errors.place_not_found.
`geocode`	HTTP and MCP	Forward-geocode an address or reverse-geocode lat/lng so search can run from a pin or a named area.
`navigate`	HTTP and MCP	Return secret-free map deep links and web URLs for a place or coordinate.
`plan_itinerary`	HTTP and MCP	Build a structured plan from trip bounds, place cards, and preferences. Weather uses Open-Meteo WMO codes via weather.wmo.* keys. Trip screens stay on the caller.
Place chat	HTTP only`POST /v1/chat`	Natural-language tool loop. The server runs the same tools. Do not use chat as the only way to search.
`Tripadvisor.enrich`	HTTP only	Optional ratings and content on HTTP search. Match by name and location. Never pass a Google place_id as a Tripadvisor id. Not an MCP tool argument.

2. Architecture

Who calls

App BFFs — what2eat.food and where2play.place, server to server
MCP hosts — Cursor, ChatBox, and similar

Callers must see the agent id places-agent (MCP serverInfo.name and HTTP field agent). That string is not localized.

3. Get a key

An admin issues a caller API key in this app. HTTP and MCP use the same key. Send it as:

Authorization: Bearer <caller_api_key>

A deleted or regenerated secret is rejected. The plaintext is shown only at create and regenerate.

4. HTTP

App BFFs call places-agent server-to-server over HTTPS. Keep the caller API key on your backend only — never in browser code, client bundles, or NEXT_PUBLIC_* variables.

Production base URL

https://places.agent-mate.ai

Health check (no auth)

Confirm the service is up before wiring tools. A homepage 200 response alone is not enough.

https://places.agent-mate.ai/v1/health

Tool routes

All tool routes use POST with Content-Type: application/json, except health. Send Authorization on every tool call.

GET  /v1/health
POST /v1/search_restaurants
POST /v1/search_places
POST /v1/plan_itinerary
POST /v1/get_place_details
POST /v1/geocode
POST /v1/navigate
POST /v1/chat

Authorization header

Authorization: Bearer <caller_api_key>

Response envelope

JSON includes agent (must be places-agent), ok, data, and optional skipped[] entries with provider and reason_key. Missing or invalid keys return errors.caller_unauthorized.

Map vendors (providers[])

Use exact ids GOOGLE_MAPS and/or AMAP in each request body. Omitting providers defaults to GOOGLE_MAPS only. Tripadvisor is enrich-only on HTTP search (enrich.tripadvisor) — not an MCP tool argument.

Example: search restaurants

curl -s -H "Authorization: Bearer <caller_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"query":"restaurant","providers":["GOOGLE_MAPS"],"locale":"EN"}' \
  https://places.agent-mate.ai/v1/search_restaurants

5. MCP

MCP hosts connect with the same caller API key. Tool names and JSON inputs match HTTP. initialize must return serverInfo.name places-agent.

Cursor — Streamable HTTP URL

Use /mcp for Cursor and other Streamable HTTP MCP clients.

https://places.agent-mate.ai/mcp

.cursor/mcp.json

Remote MCP servers in Cursor use url and headers — not command and args (those are for local stdio servers). Paste the JSON below into your project .cursor/mcp.json, or open Cursor Settings → MCP → Edit config. Reload Cursor after saving.

.cursor/mcp.json

{
  "mcpServers": {
    "places-agent": {
      "url": "https://places.agent-mate.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PLACES_AGENT_CALLER_KEY}"
      }
    }
  }
}

Set PLACES_AGENT_CALLER_KEY in your environment (Cursor expands ${env:…} in mcp.json), or replace the header value with Bearer pa_… literally.

ChatBox — remote SSE URL

Type Remote (HTTP/SSE). Enable MCP tools for the chat. Do not point ChatBox at /mcp — SSE lives at /sse (POST initialize may also use /sse on this server).

https://places.agent-mate.ai/sse

ChatBox authorization header

Authorization=Bearer <caller_api_key>

MCP tools exposed

Natural-language chat and Tripadvisor enrich are HTTP-only (/v1/chat and search enrich). MCP exposes:

search_restaurants
search_places
plan_itinerary
get_place_details
geocode
navigate

The same JSON body should return the same card count and skipped[] on HTTP and MCP (Feature 11).