// troubleshooting

MCP connection and auth

Fixing 401s and 403s from the MCP endpoint, expired or invalid tokens, OAuth that will not finish, and tools that do not show up until the client refreshes.

Every MCP client connects to one endpoint, https://mcp.superagnt.com/mcp. The workspace and the server are worked out from the credential, so the URL carries no ids. There are two ways to authenticate:

OAuth. A client that speaks OAuth needs only the URL: it discovers the endpoints, registers itself, opens a sign-in page for a person, and holds the tokens.
A bearer token for one workspace MCP server, created in the superagnt app at https://app.superagnt.com and sent as Authorization: Bearer <token>.

Per-client setup is on Connect your client, and the OAuth endpoints are on Authentication.

401: the connection is not authenticated

A 401 comes back before any tool runs, as a JSON-RPC error with code -32001. The WWW-Authenticate header points at the server's OAuth metadata, which is what starts the sign-in flow in an OAuth client.

401 on the MCP endpointhttp

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.superagnt.com/.well-known/oauth-protected-resource/mcp", error="invalid_token", error_description="Missing Authorization header"

{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Missing Authorization header"}}

Message	What it means	What to do
`Missing Authorization header`	No credential was sent.	An OAuth client should now open a sign-in page; a person approves it in the browser. A token client needs `Authorization: Bearer <token>`.
`Invalid MCP server token`	The token is unknown or was revoked.	Create a new token for the server in the superagnt app, or connect with OAuth instead.
`Invalid MCP OAuth token`	The OAuth access token is unknown or was revoked.	Reconnect the client so a person signs in again.
`MCP OAuth token expired`	Normal. Access tokens last one hour.	The client refreshes on its own with its refresh token and retries. If it keeps failing, reconnect.

Refresh tokens last 30 days. Once one has expired or been revoked, a person has to sign in again. Some clients do not ask for a new sign-in when a refresh fails and keep sending the dead token instead. If the same 401 repeats after a refresh, remove the connection in the client and add it again.

403: authenticated, but not for this

A 403 means the credential is real but cannot be used here. It comes back in the REST envelope, {"success": false, "error": {"code": "UNAUTHORIZED", "message": "..."}}:

Message	What it means	What to do
`Only workspace_mcp scoped tokens may call the canonical MCP endpoint.`	A REST API key (or another kind of key) was sent to the MCP endpoint.	Use OAuth or the MCP server token. REST API keys only work on `https://api.superagnt.com`.
`MCP server token was rotated`	A newer token replaced this one.	Use the current token from the superagnt app.
`MCP OAuth token is not valid for this server`	The OAuth token was issued for a different server.	Reconnect using that server's own URL.
`This token is scoped to a workspace MCP server endpoint and cannot be used on the public API.`	The reverse: an MCP server token was sent to the REST API.	Use a workspace API key for REST.

A 404 with "error": "unknown_facet" means the path after /mcp/ is not a known entry point. The body lists valid_facets; use one of those, or the bare /mcp.

Tools you expect are missing

A workspace MCP server starts with a small set of tools, and more families are switched on as you need them. To find and enable one:

Call agnt_tools_search with what you are looking for, for example a data source or a vendor name. It returns matching families and whether each is enabled.
Call agnt_tools_enable with the family id. The change is saved on the server right away.
Call agnt_tools_list_enabled to confirm what the server now serves.

After enabling, your own tool list may still be the old one. The server sends a notifications/tools/list_changed message, but most clients ignore it. That is expected, not a failure, and calling agnt_tools_enable again does not help. agnt_tools_search always shows the true state. To make the client load the new list:

Client	What to do
Claude, as a claude.ai connector (also how Claude Code connects when signed in with a Claude account)	Refresh or reconnect the connector under Customize, then Connectors on claude.ai, then start a new session. A new session alone is not enough, because the tool list is cached on the claude.ai side.
Claude Code with the server in its local config	Start a new session, or run `/mcp` and choose Reconnect.
ChatGPT	Settings, then Apps and Connectors, then this connector, then Refresh. Then start a new chat.
Codex CLI	Quit and restart codex. It never reloads tools mid-session.
Grok on the web	Start a new conversation. If the tools are still missing, remove the connector and add it again.
Hermes and OpenClaw	They reload on their own. If not, run `/reload-mcp` (Hermes) or `openclaw mcp reload`.
Callers that list tools on every request	Nothing to do.

Unknown tool

Unknown tool '<name>' (JSON-RPC -32601) means this server does not serve that tool to you. Either it is not enabled (see above), the name is misspelled, or your client is holding an old tool list. A deployed agent gets the tools its configuration lists, and that configuration is changed by whoever builds the agent, not by the agent at runtime.

Grouped tool names

Some clients see grouped tools, such as agnt_support_read, instead of one tool per operation. A grouped tool takes an action plus that action's arguments. Calling it wrong returns a tool error with code: "VALIDATION_ERROR" and one of these in error. Nothing ran.

error	What went wrong	What to do
`MISSING_ACTION`	No `action` was given.	Re-call with one of `valid_actions`.
`UNKNOWN_ACTION`	The `action` is not one this tool routes.	Pick one of `valid_actions`.
`MISSING_REQUIRED`	The action's required arguments are missing.	The error lists them in `missing` and includes `input_schema`. Re-call with them.
`INVALID_ARGUMENTS`	The arguments were not a JSON object.	Send an object with an `action` field.