Skip to main content
Every entry below is a failure we hit while building and deploying this server. The symptom is rarely descriptive, which is why the causes are written out in full.
Most often the client is presenting a different Host than the one you tested. The server validates the hostname on every request and returns 403 for anything it does not serve, with a message naming the rejected host — but that message is inside the response body, and most clients surface only a generic connection error.Confirm the URL in the client matches exactly, including the scheme and the /mcp path. A connector configured against an older address will keep failing after the address changes.
The client is probing for OAuth. Before connecting, Claude and ChatGPT request /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server and /register.Those paths return 404 on this server, which is correct — it signals that no authorization flow is required. A 401 there would instead be read as “OAuth is required but you are not authenticated”, and the client would abandon the connection.If you are proxying the endpoint through your own infrastructure, make sure your proxy does not convert those 404 responses into 401 or 403. That single change breaks every connector.
If the endpoint is behind a CDN or WAF configured for browser traffic, bot protection may drop server-to-server clients before they reach the application. MCP clients are backend HTTP clients, not browsers — they have no browser fingerprint and will be scored accordingly.The signature is distinctive: your own curl from a laptop succeeds, the client fails, and there is no corresponding entry in the application log because the request was terminated at the edge. Check the edge security event log rather than the application log.
The response is Server-Sent Events, not bare JSON. jq is choking on event: message.Pipe through sed first:
Requesting Accept: application/json alone does not fix this — it returns Not Acceptable. The Accept header must list both application/json and text/event-stream.
There is no result in the response, which means there is an error you are not looking at. Replace the filter with jq . to see the whole payload. The error object carries a message that usually names the exact problem.
You are sending MCP-Protocol-Version: 2026-07-28 with a request body that lacks the envelope that revision requires. In 2026-07-28 there is no initialize handshake — the protocol version, client info and client capabilities travel in _meta on every request.
Real clients build this for you. It only comes up when hand-writing curl. The simpler option for a smoke test is to omit the MCP-Protocol-Version header entirely — the server handles the older protocol era, which does not require the envelope.
The client is calling with an argument name the tool no longer has. Clients cache tool schemas at connection time and do not refresh them on their own — after a schema change, the agent keeps sending the old arguments indefinitely.The error message names the argument the server expects, and the agent will often try to “correct” itself back to the cached name, producing the same error in a loop.Cursor and Claude Code: restart the client. Claude and ChatGPT connectors: remove the connector and add it again. Toggling it off and on in a conversation does not refetch the schema.
Both Claude and ChatGPT ship general-purpose place lookup. For a plain geocoding question, the model may well choose the built-in tool — it is not wrong to do so, and it will not tell you which one it used unless asked.Questions that only Placematic can answer — territory assignment, delivery terms, truck-legal routing with dimensions — do not have this problem, because no built-in tool covers them.If you need certainty about provenance for a given question, ask the agent to state which tool it used, or check the tool call record in the client.
The address was not an address. Vague descriptors like “downtown Chicago” get tokenised, and the geocoder matches whatever fragment it can — in that specific case, a street in Omaha, Nebraska.Geocoding has no “I don’t know” mode; it returns the best available match. Resolve vague locations to a city and state before calling, or ask the user which specific address they mean.
Check whether dimensions were passed. transport_mode: "truck" alone selects a routing engine; it does not supply the vehicle profile. Without height, weight and length, the result is a generic truck route.The difference is measurable: for one 28-mile dispatch, adding full dimensions returned a route 1.6 miles shorter and ten minutes slower, because it avoided roads the vehicle could not legally use. A dispatcher planning against the dimensionless figure is late.
On Business, Enterprise and Edu plans it is a workspace setting, not a personal one. An administrator enables it under Workspace Settings → Permissions & Roles → Connected Data. No amount of searching personal settings will surface it.On personal plans it is under Settings → Apps → Advanced settings. It is web-only — the desktop and mobile apps do not offer custom connectors.

​
Still stuck

Email hello@placematic.com with the request you sent, the full response body including headers, and the client and version. During beta, MCP Server support is best-effort and is not covered by the response times in the Placematic SLA.