# Troubleshoot the MCP server This page lists the symptoms you can meet with the [Azion MCP servers](/en/documentation/devtools/mcp/), each with its cause and its fix. Authentication and connection come first, then missing tools, the client configuration, the tool answers, and sign-in. When a symptom persists, contact Azion support as [Support guidelines](/en/documentation/support/) describes, with the error message, the server URL, the client and its version, the configuration without the token, and the steps that reproduce the symptom. --- ## The server answers 401 with No authentication provided The client cannot connect, and the server answers `401` with this body: ```json {"jsonrpc":"2.0","error":{"code":-32001,"message":"No authentication provided"},"id":null} ``` The request reached the server without an `Authorization` header. The client configuration has no header, or the client does not send it. - **Add the header to the client configuration**: send `Authorization: Token [TOKEN VALUE]` with your personal token. For the configuration of each client, refer to [Agent Setup](/en/documentation/agent-setup/). The server answers `200` to the client, and the client lists the tools. --- ## The server answers 403 Authentication failed or 401 OAuth validation failed The client sends an `Authorization` header, and the server still refuses the request. The status and the message name the problem: | Status | Message | Cause | | ------ | ------------------------- | ------------------------------------------------------ | | `403` | `Authentication failed` | The value after `Token` is not a valid personal token. | | `401` | `OAuth validation failed` | The personal token was sent with the `Bearer` scheme. | Both come as JSON-RPC error objects with the code `-32001`. - **Send the personal token with Token**: `Authorization: Token [TOKEN VALUE]`. A personal token sent with `Bearer` fails. - **Check the token**: a personal token is 40 characters long and starts with `azion`. Copy the whole value. Check that the token is active, has not expired, and has the permissions you need. To create another one, refer to [How to manage a personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/). - **Test the connection with MCP Inspector**: run `npx @modelcontextprotocol/inspector`, choose the `streamable-http` transport, enter the server URL, and pass the header with your token. > **Caution** > > Keep your personal token out of version control and out of messages to other people. Remove it from logs, screenshots, and `dry_run` previews before you send them. The server answers `200`, and the client lists the tools. --- ## The client times out or cannot reach the server A request times out, the server sends no response, or the client reports a network error. The client points at the wrong URL, or the network between the client and the server blocks the connection. - **Check the URL**: each server answers at the `/mcp` path of its host, such as `https://docs-mcp.azion.com/mcp`. For every URL, refer to [Tools and resources](/en/documentation/devtools/mcp/tools/). - **Test that the server is reachable**: a request without a token answers `401`. A `401` means the server is reachable. A timeout or a connection error means the network does not reach it. - **Try another network**: a VPN can interfere. A firewall or a proxy must allow HTTPS traffic to the host of each server you use, such as `docs-mcp.azion.com`. - **Test your token outside the client**: send the `initialize` request with `curl`. This request opens a connection to the docs server with your token: ```bash curl -s https://docs-mcp.azion.com/mcp \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"0.1"}}}' ``` A response that carries a `result` with the protocol version and the capabilities of the server means the server and the token work, and the fix is in the client configuration. A `401` or `403` points to the header, as the sections above describe. --- ## A tool is missing or a call fails with Tool not found The agent does not offer a tool you expect, or a tool call fails because the server does not know the tool. Each server exposes the tools of its own area, and the agent sees only the tools of the servers it connects. A tool from an area whose server is not connected is missing, and a call that names a tool on the wrong server fails. - **Connect the server that owns the tool**: the docs server searches and returns guides, build manages applications, rules, functions, workloads, and cache purge, secure manages firewalls, WAF, DNS, and certificates, observe manages data streams, reports, and GraphQL queries, and storage manages Object Storage and SQL Database. For the tools of each server, refer to [Tools and resources](/en/documentation/devtools/mcp/tools/). - **Check the connected servers**: in Claude Code, `claude mcp list` names each server and its status. - **Call the tools the server lists**: the agent calls only the tools that `tools/list` returns for each server. The agent lists the tool, and the call answers. --- ## The connection fails with TLSV1\_ALERT\_PROTOCOL\_VERSION The client fails the TLS handshake with an error such as `SSLError TLSV1_ALERT_PROTOCOL_VERSION`. The servers accept TLS 1.3 only. A client built on a TLS library without TLS 1.3, such as LibreSSL 2.8.3, cannot connect. - **Run the client on a runtime with TLS 1.3**: a runtime whose TLS library supports TLS 1.3 connects, such as Node.js 24. - **Check the TLS library of your tool**: a script or a proxy between the client and the server must also support TLS 1.3. The handshake completes, and the server answers the request. --- ## The client shows no Azion tools The client shows no Azion tools, reports `No tools available`, or does not recognize the commands. The client does not support MCP, has not loaded its configuration, or has not registered the server. - **Check MCP support**: use a client version that supports MCP. Update the client if it does not. - **Check the configuration location**: Windsurf reads `.codeium/windsurf/mcp_config.json`. For each client, refer to [Agent Setup](/en/documentation/agent-setup/). - **Check that the server is registered**: in Claude Code, `claude mcp list` names the servers it knows. For the setup, refer to [Claude Code + Azion](/en/documentation/agent-setup/claude-code/). - **Restart the client**: close and reopen the application so it reads the configuration again. The client lists the tools of each server it connects. --- ## The client reports Invalid JSON The client reports `Invalid JSON` and does not load the configuration. The configuration file breaks a JSON rule. Common causes are a missing comma between properties, a trailing comma, single quotes instead of double quotes, and an unclosed bracket or brace. - **Validate the file**: `cat mcp_config.json | python -m json.tool` prints the file when it is valid and names the first error when it is not. - **Compare with a valid configuration**: a client that starts the server through `mcp-remote` reads a configuration of this shape. ```json { "mcpServers": { "azion-docs": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://docs-mcp.azion.com/mcp", "--header", "Authorization: Token [TOKEN VALUE]" ] } } } ``` The client loads the configuration and lists the tools. --- ## The client fails with npx command not found The client fails with `npx: command not found` or `Node.js is required`. `mcp-remote` runs on Node.js. It needs Node.js 18 or later, and `npx` comes with npm. - **Check the installed versions**: `node --version` and `npm --version` print the versions, or fail when Node.js is missing. - **Install Node.js**: on macOS, run `brew install node`. On Ubuntu or Debian, run `sudo apt install nodejs npm`. - **Update npm**: run `npm install -g npm@latest`. `npx -y mcp-remote@latest` starts the bridge. For the clients that use it, refer to [Agent Setup](/en/documentation/agent-setup/). --- ## The client fails with Cannot find module mcp-remote The client fails with `Cannot find module 'mcp-remote'`, or the package install fails. The npm cache or the installed copy of `mcp-remote` is broken or missing. - **Clear the npm cache**: run `npm cache clean --force`. - **Install the package globally**: run `npm install -g mcp-remote`. - **Run the latest version**: start the bridge with `npx mcp-remote@latest`. The bridge starts and prints `Proxy established successfully`. --- ## A search returns documents that do not match the query A search tool returns no result, a partial result, or general answers instead of Azion information. The search tools rank documents by how close they are to the words of the query, not by what the query means. A broad query can rank a document about another product or operation first. - **Name the product and the task**: ask "How do I configure cache TTL for images in Azion?" instead of "Help with cache". - **Name the tool or the source**: ask "Search Azion docs for Rules Engine cache configuration". - **Ask for more documents**: the search tools take `docsAmount`, which defaults to `5`. For the inputs, refer to [Tools](/en/documentation/devtools/mcp/tools/#docs-server-tools). - **Split the request**: ask one question per prompt. The tool returns documents about the product and the task you named. --- ## The GraphQL tool answers It was not possible to retrieve the requested information `create_graphql_query`, on the observe server, returns the text `It was not possible to retrieve the requested information with GraphQL.` instead of a query. The text then points to the GraphQL API documentation. The tool writes a query for your goal and runs it against the selected GraphQL endpoint of your account, with your token. The tool returns this text when it cannot produce a query that runs. The server does not return the cause to the client. - **Check that the data exists**: confirm that the GraphQL API carries the data you ask for. For the datasets, refer to [GraphQL API](/en/documentation/devtools/graphql/). - **Check the data source**: `dataSource` takes `real-time-metrics`, `real-time-events`, `accounting`, or `consumption`. Pick the one that holds the data. - **Write the query yourself**: build the query from the GraphQL API documentation and run it there. You get the data from a query that the GraphQL API runs. --- ## Tool calls answer slowly Tool calls take a long time to answer. The network path to the server is slow, many requests run at once, or the query is broad. `create_graphql_query`, on the observe server, also generates and runs queries against your account, so it takes longer than a search. - **Check the network**: use a stable connection. `ping docs-mcp.azion.com` measures the latency to the docs server. - **Send fewer requests at once**: run fewer concurrent tool calls. - **Narrow the query**: ask a specific question instead of a broad search. Tool calls answer in less time. --- ## Related resources - [MCP server quickstart](/en/documentation/devtools/mcp/quickstart.md): Create a personal token and connect a client, the setup that most fixes on this page return to. - [Tools and resources](/en/documentation/devtools/mcp/tools.md): The URL and the tools of each server, their inputs, and the resources the docs server exposes. - [How the MCP server works](/en/documentation/devtools/mcp/how-it-works.md): How the servers authenticate a request, answer it, and preview a write with dry\_run. - [Agent Setup](/en/documentation/agent-setup.md): The configuration of each coding agent, including the header scheme it sends.