Troubleshooting

Tool calls return 401 Unauthorized

What you see: A tool call fails with 401 Unauthorized.

Why it happens: Two paths can return a 401, depending on the endpoint:

• OAuth path (/mcp). The five tenant tools require a valid OAuth 2.1 Bearer JWT. A 401 means the request carried no token, the token was revoked (you removed the app from Settings → Connected apps), the access token expired and was not refreshed, or the token was minted for a different audience than https://app.placeoptimizer.com/mcp.
• Console path (/api/v1/mcp). The console-internal tools require a valid PlaceOptimizer session with an active organization and at least the member role. A 401 means the session expired or was revoked.

Fix:

1. For an OAuth connection, reconnect the client so it runs the authorization flow again, or check that you have not revoked the app in Settings → Connected apps. Tokens minted for /mcp carry the audience https://app.placeoptimizer.com/mcp; a token from another service will not verify.
2. For the console path, sign in to app.placeoptimizer.com, confirm you belong to an organization with at least the member role (Settings → Organizations), and re-run the tool call.

If you signed out, or revoked the session from Settings → Devices, the client must establish a new session before the tools work again.

The public tools work but no tenant tools appear

What you see: Your assistant lists only ping_console, get_audit_overview, and get_public_endpoints, and none of the location/review/post tools.

Why it happens: The three public tools need no authentication. The five tenant tools appear only after the client completes the OAuth 2.1 authorization flow — if the client has never been authorized, its authorization was revoked, or its access token expired, tools/list shows the public surface only.

Fix: Ask your assistant to authorize, or reconnect the client so the browser opens the PlaceOptimizer sign-in and consent screen, and approve the requested scopes. Once the client holds a valid token, all eight tools appear. See Authentication.

The endpoint reports an unsupported protocol version

What you see: initialize or tools/list fails with Unsupported protocol version.

Why it happens: PlaceOptimizer speaks MCP v2 (spec revision 2026-07-28). Clients speaking older protocol revisions (for example 2025-06-18) are rejected with the list of supported revisions in the error payload.

Fix: Upgrade your client to one that negotiates the 2026-07-28 protocol revision, or use the MCP Inspector against the endpoint to confirm the negotiation.

No tools show up in my client

What you see: The server connects but your assistant does not list any PlaceOptimizer tools.

Fix:

1. Restart the client after any config change — most clients only read the MCP configuration at startup.
2. Check the server URL is exactly https://app.placeoptimizer.com/mcp (no trailing slash in the transport, no path typo).
3. Confirm your client supports remote MCP servers over HTTP — not all clients do. See Setup for the supported clients.
4. Ask the assistant "What PlaceOptimizer tools do you have?" — the tools are listed on demand, not announced in chat.

Connection fails or times out

What you see: The client reports the server as unreachable.

Fix:

1. Confirm the endpoint is up: curl -i https://app.placeoptimizer.com/mcp should return a 405 Method Not Allowed with Allow: POST — the endpoint is POST-only and answers other methods with 405 rather than 404.
2. Check you are not behind a proxy that strips the MCP-Protocol-Version header or the Accept: application/json, text/event-stream header.
3. If it is a transient issue, wait a moment and retry.

I have a question or found a bug

PlaceOptimizer is in public beta. For support, questions about access, or bug reports, email hello@invarya.com. If you are reporting a bug, include the tool name, the endpoint, and the exact error payload.