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

  1. Verify the server is running and the URL is correct.

  2. 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.

  3. Ensure the port is reachable from the machine running the client. Check firewall rules and, where applicable, your VPN configuration.

  4. If the server is behind a reverse proxy, confirm that mcpPublicUrl is set to the correct public URL. See Reverse proxy deployments.

The OAuth flow does not complete

  1. Confirm that your default browser is available. The authorization flow needs a browser for sign-in and for the consent step.

  2. If the browser does not open automatically, check the client logs for the authorization URL and open it manually.

  3. Make sure that the redirect URI registered during dynamic client registration is reachable from the browser.

  4. Verify your user credentials are correct.

  5. 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 client receives 401 errors after a successful sign-in

  1. The access token may have expired. The client should refresh it automatically. Check the client logs for refresh errors.

  2. 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.

  3. 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.

Related topics

  • Authorization — token lifetimes, the refresh flow, and how to revoke access.

  • Access control — role requirements and development package checks.

  • Connect an MCP client — how to remove and re-add a server to repeat the authorization flow.

  • Deployment — HTTPS requirements and reverse proxy configuration, which are the most common sources of connection failures.

  • Configuration reference — all MCP configuration keys, including mcpPublicUrl.