MCP Troubleshooting

This guide helps resolve common issues with MCP configuration and usage.

Connection issues

Authentication failed

Symptoms:

• Error: “401 Unauthorized"
• "Invalid token” message
• Connection refused by MCP server

Solutions:

1. Verify token format:

   # Correct format with Bearer prefix
   Authorization: Bearer YOUR_PERSONAL_TOKEN
   
   # Note: Cursor uses Token prefix
   Authorization: Token YOUR_PERSONAL_TOKEN

2. Check token validity:

   • Navigate to Azion Console
   • Verify token is active and not expired
   • Ensure token has necessary permissions

3. Test with MCP Inspector:

   npx @modelcontextprotocol/inspector

   Configure as streamable-http with your token to validate connection.

Connection timeout

Symptoms:

• Request times out after 30+ seconds
• No response from MCP server
• ”Network error” messages

Solutions:

1. Check server URL:

   • Correct URL: https://mcp.azion.com
   • Ensure no typos in URL

2. Test network connectivity:

   # Test server availability
   curl -I https://mcp.azion.com

3. Try alternative connection:

   • Consider using a different network connection
   • Check if VPN is interfering

4. Check firewall/proxy settings:

   • Ensure HTTPS traffic to mcp.azion.com is allowed
   • Verify proxy configuration if applicable

Tools not appearing

No tools listed in assistant

Symptoms:

• Code assistant doesn’t show Azion tools
• ”No tools available” message
• Commands not recognized

Solutions:

1. Verify MCP support:

   • Ensure your code assistant version supports MCP
   • Update to latest version if needed

2. Check configuration syntax:

   Claude Code

   claude mcp list  # Should show azion-mcp

   Cursor

   Verify JSON syntax in settings is valid

   Windsurf

   Check .codeium/windsurf/mcp_config.json exists and is valid JSON

3. Restart the assistant:

   • Close and reopen the application
   • For Claude Code: claude serve --restart

Tool execution errors

”Tool not found” error

Symptoms:

• Specific tool names not recognized
• ”Unknown tool” errors

Solutions:

1. Verify tool name: Correct tool names:

   • search_azion_docs_and_site
   • search_azion_code_samples
   • search_azion_cli_commands
   • search_azion_api_v3_commands
   • search_azion_api_v4_commands
   • search_azion_terraform
   • create_rules_engine
   • create_graphql_query
   • deploy_azion_static_site

2. Check API profile:

   • v3 profiles may have limited tool access
   • Consider upgrading to v4 profile

Empty or incomplete responses

Symptoms:

• Tools return no results
• Partial responses
• Generic answers instead of Azion-specific information

Solutions:

1. Refine your query:

   ❌ "Help with cache"
   ✅ "How do I configure cache TTL for images in Azion?"

2. Use specific tool hints:

   "Search Azion docs for Rules Engine cache configuration"

3. Break complex requests:

   • Split multi-part questions
   • Ask for clarification if needed

Configuration file issues

JSON parsing errors

Symptoms:

• “Invalid JSON” errors
• Configuration not loaded

Solutions:

1. Validate JSON syntax:

   # Use a JSON validator
   cat mcp_config.json | python -m json.tool

2. Common JSON issues:

   • Missing commas between properties
   • Trailing commas (not allowed in JSON)
   • Incorrect quote types (must use double quotes)
   • Unclosed brackets or braces

3. Example valid configuration:

   {
   "mcpServers": {
     "azion": {
       "command": "npx",
       "args": [
         "mcp-remote",
         "https://mcp.azion.com",
         "--header",
         "Authorization: Bearer YOUR_TOKEN"
       ]
     }
   }
   }

Node.js related issues

npx command not found

Symptoms:

• “npx: command not found"
• "Node.js is required”

Solutions:

1. Install Node.js:

   # Check if installed
   node --version
   npm --version
   
   # Install via package manager
   # macOS
   brew install node
   
   # Ubuntu/Debian
   sudo apt install nodejs npm

2. Update npm:

   npm install -g npm@latest

mcp-remote package issues

Symptoms:

• “Cannot find module ‘mcp-remote‘“
• Package installation fails

Solutions:

1. Clear npm cache:

   npm cache clean --force

2. Install globally:

   npm install -g mcp-remote

3. Use specific version:

   npx mcp-remote@latest

Performance issues

Slow response times

Solutions:

1. Optimize connection:

   • Ensure stable network connection
   • Minimize concurrent requests

2. Optimize queries:

   • Be specific in requests
   • Avoid overly broad searches

3. Check network latency:

   ping mcp.azion.com

Getting help

If issues persist after trying these solutions:

1. Contact support:

   • Include error messages
   • Specify code assistant and version
   • Provide configuration (without tokens)
   • Describe steps to reproduce

2. Community resources:

   • Azion Discord
   • Azion Forum