Troubleshooting

Use the following checks to diagnose connection problems. Most errors come from network reachability, an incorrect public URL behind a reverse proxy, or expired tokens.

The client cannot connect

Verify the server is running and the URL is correct.
Check the server logs for the messages MCP server registered at /mcp and MCP OAuth provider initialized. If either is missing, the MCP server is not enabled.
Ensure the port is reachable from the machine running the client. Check firewall rules and, where applicable, your VPN configuration.
If the server is behind a reverse proxy, confirm that mcpPublicUrl is set to the correct public URL. See Reverse proxy deployments.

`mcp` returns 404 or the client reports the endpoint does not exist

The MCP route is not mounted. On startup the server skips mounting /mcp and logs a warn explaining why, when either of these is true:

mcpPublicUrl is not a valid URL. Fix the value (scheme, host, and optional port only, no path), or leave it empty to fall back to the bind URL.
The instance runs in production without HTTPS. MCP OAuth requires HTTPS in production. Enable SSL, set mcpPublicUrl to the public https:// URL when a reverse proxy terminates TLS, or use a local development instance for http:// testing.

Check the server log at startup for the exact reason. See Configuration reference for the mcpPublicUrl key and Reverse proxy deployments.

The connection silently fails on localhost

The client shows the server but authorization never completes, and no error is shown in the terminal. This is almost always a scheme mismatch: mcpPublicUrl (or the URL you registered) uses https:// while the server actually runs plain HTTP. The tell-tale log line is:

info: SameSite:None can only be set for cookies when running on HTTPS.
HTTPS is not enabled, reverting to Strict

Set the URL scheme to http:// for a local HTTP instance, and reserve https:// for instances with SSL enabled or a TLS-terminating proxy in front. A scheme mismatch is also logged as a startup warn. See HTTPS and local development.

A fresh instance rejects sign-in or returns no tools

The database was never initialized, so there is no admin user or access-control data to authenticate against. Stop the server, run ./planet9 --initialize once (planet9.exe --initialize on Windows), then start it again. See Deployment: Initial setup.

The OAuth flow does not complete

Confirm that your default browser is available. The authorization flow needs a browser for sign-in and for the consent step.
If the browser does not open automatically, check the client logs for the authorization URL and open it manually.
Make sure that the redirect URI registered during dynamic client registration is reachable from the browser.
Verify your user credentials are correct.
If the consent page is shown but the Approve button returns a No pending authorization error, the session lost its pending entry. Start the authorization flow again from the client.

The access token may have expired. The client should refresh it automatically. Check the client logs for refresh errors.
The refresh token expires after seven days. Once it has expired, you must repeat the authorization flow. Remove the server entry and add it again.
If the response body contains {"error":"invalid_token","error_description":"Invalid or expired access token"}, the token failed verification. This can happen if the token was minted for a different MCP server, if the public URL has changed, or if the token was revoked. Reconnect to obtain a fresh token.

The client receives a 403 insufficient_scope error

The token is valid but lacks the mcp:tools scope. The response body is {"error":"insufficient_scope","error_description":"Missing required scope: mcp:tools"}. Request a new token with scope=mcp:tools and reconnect. Most clients do this automatically.

A tool returns an access denied error

Your user account is missing the role required by the tool. Review the role list in Access control and ask an administrator to grant the missing role, or operate on the artifact through a user account that has the role.

A tool fails with a validation error

Tool calls run through the same validation pipeline as the Cockpit. The validation message identifies the field that failed. Common examples include:

Web app names that contain characters other than letters, digits, -, or _.
Tables with fields that have an unrecognized fieldType.
Adaptive entities saved without the required name, type, or settings.

Correct the input as indicated by the error message and retry.