Errors
What each refusal from the MCP server means, and what to do about it.
Two kinds of error
- The request is refused. Nothing ran: the server answers with an HTTP error status, and a client usually reports it as failing to connect.
- A tool call fails. The server answers
200with a tool result marked"isError": true, holding one line of text that says why. Your agent reads it like any other result, so it can tell you, or fix its arguments and call again.
Every tool reads and changes nothing, so a call that failed can always be made again.
The request is refused
| What you see | Why | What to do |
|---|---|---|
HTTP 401, with "error": "no_credential" and No API token presented., then where to create one |
The request had no Authorization header, or one that is not Bearer <token>. |
Send Authorization: Bearer zhos_…. In a client, check the header is in its configuration. |
| Your client says the server needs authentication, or offers you a sign-in | The same: no token reached the server. It has no sign-in to offer. | Add the header (Connect a client). |
HTTP 415, Unsupported Media Type: Content-Type must be application/json |
The POST did not say its body is JSON. |
Send Content-Type: application/json. |
HTTP 400, JSON-RPC error -32700, Parse error: the body is not valid JSON. |
The body is not valid JSON at all. | Check the body parses. In a shell, quote it in single quotes. |
HTTP 400, Parse error: Invalid JSON-RPC message |
The body is JSON, but not a JSON-RPC 2.0 message. | Send jsonrpc, method, and an id on a request. |
HTTP 400, Bad Request: Unsupported protocol version: … |
The MCP-Protocol-Version header names a version the server does not support. The message lists the ones it does. |
Send one of those, or leave the header out. |
HTTP 405, Method not allowed. |
A GET: the server has no stream of messages of its own to open. |
Nothing, for a client: it carries on without the stream. By hand, send a POST. |
JSON-RPC error -32601, Unknown method: … |
The server answers initialize, ping, tools/list and tools/call. It has no resources or prompts. |
Use a tool. |
JSON-RPC error -32603, naming params and name |
A tools/call with no tool name. |
Put the tool's name in params.name. |
No answer at all, and /v1/health does not answer either |
The MCP server cannot be reached from where you are. | Check your connection, then try again later. |
A tool call fails
Each message names the tool you called, except for a tool that does not exist.
| What you see | Why | What to do |
|---|---|---|
os.list_blockers: This token needs blockers:read; it has runs:read., then where to add it |
The token lacks the scope this tool's API route needs. The message names the scope needed and the ones the token has. | Someone who holds that scope adds it with Edit scopes on the token, under Settings → API tokens. The secret stays the same, so the client needs no change, and the next call has the scope. |
os.list_runs: the API did not accept this token; it is unknown or has been revoked. |
The token was revoked, rotated away, or mistyped. The server connects and lists tools without checking the token, so this shows on the first call. | Put a live token in the client's header. A revoked token cannot come back: create a new one. |
Unknown tool: os.list_run. |
No tool has that name. Names are exact, dots included. | List the tools, and use a name from the list. |
os.list_runs: unknown argument "enterpriseId" (it takes status, taskId, live, page, limit). |
The tool does not take that argument. Nothing was sent to the API. | Use the arguments the message names. |
os.get_run: missing required argument "runId". |
A required argument was left out. | Send it. |
os.list_runs: "limit" must be at most 200. |
The value does not fit the argument. Others read must be one of …, must be an integer, must be true or false or must be a non-empty string. |
Send a value that fits. Each tool's schema in tools/list has the limits. |
os.get_run: not found. |
The id names nothing in your enterprise. A run in another enterprise is not found either. | Check the id. os.list_runs gives run ids. |
os.list_runs failed (arguments: {…}): the API answered status 500: … |
Any other refusal or failure, with the API's status and its own message. | Read the message. A 5xx is worth trying again after a moment. |
os.list_runs: the OS API could not be reached (…). |
The MCP server could not reach the API behind it. | Try again after a moment. |
An empty list is an answer, not an error: nothing matched.