[{"data":1,"prerenderedAt":22},["ShallowReactive",2],{"$fhlqxkm9yfnek":3},{"href":4,"title":5,"description":6,"kind":7,"mark":7,"planned":8,"contributors":9,"provenance":7,"html":10,"headings":11},"\u002Fdocs\u002Fmcp\u002Ferrors","Errors","What each refusal from the MCP server means, and what to do about it.",null,false,[],"\u003Ch2 id=\"two-kinds-of-error\">Two kinds of error\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Cstrong>The request is refused.\u003C\u002Fstrong> Nothing ran: the server answers with an HTTP error status, and a client usually\nreports it as failing to connect.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A tool call fails.\u003C\u002Fstrong> The server answers \u003Ccode>200\u003C\u002Fcode> with a tool result marked \u003Ccode>"isError": true\u003C\u002Fcode>, holding one line of\ntext that says why. Your agent reads it like any other result, so it can tell you, or fix its arguments and call\nagain.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Every tool reads and changes nothing, so a call that failed can always be made again.\u003C\u002Fp>\n\u003Ch2 id=\"the-request-is-refused\">The request is refused\u003C\u002Fh2>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>What you see\u003C\u002Fth>\n\u003Cth>Why\u003C\u002Fth>\n\u003Cth>What to do\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>HTTP \u003Ccode>401\u003C\u002Fcode>, with \u003Ccode>"error": "no_credential"\u003C\u002Fcode> and \u003Ccode>No API token presented.\u003C\u002Fcode>, then where to create one\u003C\u002Ftd>\n\u003Ctd>The request had no \u003Ccode>Authorization\u003C\u002Fcode> header, or one that is not \u003Ccode>Bearer <token>\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003Ctd>Send \u003Ccode>Authorization: Bearer zhos_…\u003C\u002Fcode>. In a client, check the header is in its configuration.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Your client says the server needs authentication, or offers you a sign-in\u003C\u002Ftd>\n\u003Ctd>The same: no token reached the server. It has no sign-in to offer.\u003C\u002Ftd>\n\u003Ctd>Add the header (\u003Ca href=\"\u002Fdocs\u002Fmcp\u002Fconnect\">Connect a client\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>HTTP \u003Ccode>415\u003C\u002Fcode>, \u003Ccode>Unsupported Media Type: Content-Type must be application\u002Fjson\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The \u003Ccode>POST\u003C\u002Fcode> did not say its body is JSON.\u003C\u002Ftd>\n\u003Ctd>Send \u003Ccode>Content-Type: application\u002Fjson\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>HTTP \u003Ccode>400\u003C\u002Fcode>, JSON-RPC error \u003Ccode>-32700\u003C\u002Fcode>, \u003Ccode>Parse error: the body is not valid JSON.\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The body is not valid JSON at all.\u003C\u002Ftd>\n\u003Ctd>Check the body parses. In a shell, quote it in single quotes.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>HTTP \u003Ccode>400\u003C\u002Fcode>, \u003Ccode>Parse error: Invalid JSON-RPC message\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The body is JSON, but not a JSON-RPC 2.0 message.\u003C\u002Ftd>\n\u003Ctd>Send \u003Ccode>jsonrpc\u003C\u002Fcode>, \u003Ccode>method\u003C\u002Fcode>, and an \u003Ccode>id\u003C\u002Fcode> on a request.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>HTTP \u003Ccode>400\u003C\u002Fcode>, \u003Ccode>Bad Request: Unsupported protocol version: …\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The \u003Ccode>MCP-Protocol-Version\u003C\u002Fcode> header names a version the server does not support. The message lists the ones it does.\u003C\u002Ftd>\n\u003Ctd>Send one of those, or leave the header out.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>HTTP \u003Ccode>405\u003C\u002Fcode>, \u003Ccode>Method not allowed.\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A \u003Ccode>GET\u003C\u002Fcode>: the server has no stream of messages of its own to open.\u003C\u002Ftd>\n\u003Ctd>Nothing, for a client: it carries on without the stream. By hand, send a \u003Ccode>POST\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>JSON-RPC error \u003Ccode>-32601\u003C\u002Fcode>, \u003Ccode>Unknown method: …\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The server answers \u003Ccode>initialize\u003C\u002Fcode>, \u003Ccode>ping\u003C\u002Fcode>, \u003Ccode>tools\u002Flist\u003C\u002Fcode> and \u003Ccode>tools\u002Fcall\u003C\u002Fcode>. It has no resources or prompts.\u003C\u002Ftd>\n\u003Ctd>Use a tool.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>JSON-RPC error \u003Ccode>-32603\u003C\u002Fcode>, naming \u003Ccode>params\u003C\u002Fcode> and \u003Ccode>name\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A \u003Ccode>tools\u002Fcall\u003C\u002Fcode> with no tool name.\u003C\u002Ftd>\n\u003Ctd>Put the tool's name in \u003Ccode>params.name\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>No answer at all, and \u003Ccode>\u002Fv1\u002Fhealth\u003C\u002Fcode> does not answer either\u003C\u002Ftd>\n\u003Ctd>The MCP server cannot be reached from where you are.\u003C\u002Ftd>\n\u003Ctd>Check your connection, then try again later.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"a-tool-call-fails\">A tool call fails\u003C\u002Fh2>\n\u003Cp>Each message names the tool you called, except for a tool that does not exist.\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>What you see\u003C\u002Fth>\n\u003Cth>Why\u003C\u002Fth>\n\u003Cth>What to do\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.list_blockers: This token needs blockers:read; it has runs:read.\u003C\u002Fcode>, then where to add it\u003C\u002Ftd>\n\u003Ctd>The token lacks the scope this tool's API route needs. The message names the scope needed and the ones the token has.\u003C\u002Ftd>\n\u003Ctd>Someone who holds that scope adds it with \u003Cstrong>Edit scopes\u003C\u002Fstrong> on the token, under \u003Cstrong>Settings → API tokens\u003C\u002Fstrong>. The secret stays the same, so the client needs no change, and the next call has the scope.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.list_runs: the API did not accept this token; it is unknown or has been revoked.\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>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.\u003C\u002Ftd>\n\u003Ctd>Put a live token in the client's header. A revoked token cannot come back: create a new one.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>Unknown tool: os.list_run.\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>No tool has that name. Names are exact, dots included.\u003C\u002Ftd>\n\u003Ctd>List the tools, and use a name from the list.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.list_runs: unknown argument "enterpriseId" (it takes status, taskId, live, page, limit).\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The tool does not take that argument. Nothing was sent to the API.\u003C\u002Ftd>\n\u003Ctd>Use the arguments the message names.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.get_run: missing required argument "runId".\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A required argument was left out.\u003C\u002Ftd>\n\u003Ctd>Send it.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.list_runs: "limit" must be at most 200.\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The value does not fit the argument. Others read \u003Ccode>must be one of …\u003C\u002Fcode>, \u003Ccode>must be an integer\u003C\u002Fcode>, \u003Ccode>must be true or false\u003C\u002Fcode> or \u003Ccode>must be a non-empty string\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003Ctd>Send a value that fits. Each tool's schema in \u003Ccode>tools\u002Flist\u003C\u002Fcode> has the limits.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.get_run: not found.\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The id names nothing in your enterprise. A run in another enterprise is not found either.\u003C\u002Ftd>\n\u003Ctd>Check the id. \u003Ccode>os.list_runs\u003C\u002Fcode> gives run ids.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.list_runs failed (arguments: {…}): the API answered status 500: …\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Any other refusal or failure, with the API's status and its own message.\u003C\u002Ftd>\n\u003Ctd>Read the message. A \u003Ccode>5xx\u003C\u002Fcode> is worth trying again after a moment.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.list_runs: the OS API could not be reached (…).\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The MCP server could not reach the API behind it.\u003C\u002Ftd>\n\u003Ctd>Try again after a moment.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>An empty list is an answer, not an error: nothing matched.\u003C\u002Fp>\n",[12,16,19],{"id":13,"text":14,"level":15,"planned":8},"two-kinds-of-error","Two kinds of error",2,{"id":17,"text":18,"level":15,"planned":8},"the-request-is-refused","The request is refused",{"id":20,"text":21,"level":15,"planned":8},"a-tool-call-fails","A tool call fails",1791124519669]