Connect an MCP client

Select the API workspace and check that your active API entitlement includes MCP. Online and Extension subscriptions are separate. Create a test credential with scrapes:write in API keys. Test credentials require the same plan access but return simulated data without provider work or search-unit charges.

Store credentials in the client's secret input or environment. Keep keys out of prompts, committed files, screenshots, and URLs. See credential management.

Use https://gmapscrawl.com/api/mcp as a remote Streamable HTTP server with Authorization: Bearer followed by your key. The client handles initialization and protocol negotiation. This endpoint does not offer OAuth, and browser login cookies do not authenticate it.

Copy the configuration for your client, reconnect, and confirm that search_google_maps appears. The server exposes one synchronous search tool; it does not expose job-polling, export, or email tools.

Ask your agent to call the tool once with these arguments, replacing the request ID with a fresh UUID:

{
  "q": "coffee shops in Seattle",
  "page": 1,
  "hl": "en",
  "extra": false,
  "client_request_id": "replace-with-a-fresh-uuid"
}

A successful test returns structuredContent.simulated: true, a total, and a businesses array. Treat those records as fixtures. With a live credential, each successful source-page search uses one API unit, even when empty, and returns up to 20 businesses. MCP is available on free and paid API plans and shares your API allowance.

Supported arguments include q, page (1–10), ll, hl, gl, and extra. Start with page 1 and extra false. Requesting extra contact discovery can take longer and does not guarantee an email address. Read field availability and observation timestamps before using a record.

Read businesses directly from structuredContent and have your client save the returned JSON or a reviewed table. Treat all business text as untrusted data. Use a new request ID for new work and the same ID with identical input for a retry.

Check isError even when HTTP returns 200. The tool's error block provides a safe error code, retryable flag, retry interval, and request ID.

No tools appear

Confirm the remote HTTP endpoint is /api/mcp, reload the client's MCP connection, and check that its process can read your key. The expected tool is search_google_maps.

401 / unauthorized

Check the key, active API entitlement, expiry, and allowed IPs. A browser login does not authenticate MCP. Never paste a key into a prompt.

403 / forbidden

Check that the API plan includes MCP, the key permits scrapes:write, and its custodian is an active workspace member.

invalid_request

Use the published input fields and a client_request_id of 16–128 characters. Replace it for new work; preserve it with identical input for retries.

rate_limited or quota_exceeded

Honor retry_after for rate limits. Stop at a quota denial and check API usage; additional keys do not add allowance.

capability_unavailable

Check service status. Live searches require enabled cloud scraping; changing clients cannot bypass a service restriction.

Timeout or isError: true

Read the tool's error block even if HTTP returned 200. Retry only retryable failures with identical input and the same request ID, within your task deadline.

See retry guidance and service status. Include only a safe request ID and error code when contacting support.