Troubleshoot the MCP server

This page lists the symptoms you can meet with the Azion MCP servers, 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 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:

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.

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:

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

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.
• 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:

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

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.

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