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

OAuth and SSO issues

Token validation fails

Symptoms:

• “Invalid token” after OAuth flow
• UserInfo returns 401

Solutions:

1. Verify token format:

   • Ensure the token is sent with Bearer prefix
   • Check if using correct SSO domain (production vs stage)

2. Check token expiration:

   • OAuth tokens expire after a set period
   • Request a new token if expired

3. Verify SSO endpoints:

   • Production: https://sso.azion.com/oauth/*
   • Stage: https://stage-sso.azion.com/oauth/*

Client not authorized

Solutions:

1. Verify client ID and secret are correct
2. Check redirect URI matches exactly what’s configured in SSO
3. Ensure required scopes are enabled for the client

Environment-specific issues

Stage environment not responding

Solutions:

1. Verify URL:

   • Stage URL: https://stage-mcp.azion.com
   • Production URL: https://mcp.azion.com

2. Check environment status:

   • Stage may have different availability than production
   • Use production for critical workflows

Local development issues

Solutions:

1. Verify server is running:

2. Check environment variables:

3. Restart local server:

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

Next steps

• MCP Local Development
• MCP Cache Testing