# MCP Troubleshooting

import Code from '~/components/Code/Code.astro'

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**:
   <Code lang="bash" code={`
   # 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](https://console.azion.com/personal-tokens)
   - Verify token is active and not expired
   - Ensure token has necessary permissions

3. **Test with MCP Inspector**:
   <Code lang="bash" code={`
   npx @modelcontextprotocol/inspector
   `} />
   Configure as `streamable-http` with your token to validate connection.

:::warning
  Never share your Personal Token or commit it to version control.
:::

---

### 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**:
   <Code lang="bash" code={`
   # 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**:
   <details>
   <summary>Claude Code</summary>
   <Code lang="bash" code={`
   claude mcp list  # Should show azion-mcp
   `} />
   </details>
   
   <details>
   <summary>Cursor</summary>
   Verify JSON syntax in settings is valid
   </details>
   
   <details>
   <summary>Windsurf</summary>
   Check `.codeium/windsurf/mcp_config.json` exists and is valid JSON
   </details>

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**:
   <Code lang="plaintext" code={`
   ❌ "Help with cache"
   ✅ "How do I configure cache TTL for images in Azion?"
   `} />

2. **Use specific tool hints**:
   <Code lang="plaintext" code={`
   "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**:
   <Code lang="bash" code={`
   # 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**:
   <Code lang="json" code={`
   {
     "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**:
   <Code lang="bash" code={`
   # 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**:
   <Code lang="bash" code={`
   npm install -g npm@latest
   `} />

### mcp-remote package issues

**Symptoms:**
- "Cannot find module 'mcp-remote'"
- Package installation fails

**Solutions:**

1. **Clear npm cache**:
   <Code lang="bash" code={`
   npm cache clean --force
   `} />

2. **Install globally**:
   <Code lang="bash" code={`
   npm install -g mcp-remote
   `} />

3. **Use specific version**:
   <Code lang="bash" code={`
   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**:
   <Code lang="bash" code={`
   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**:

<Code lang="bash" code={`# Check if azion dev is running
curl http://localhost:3333`} />

2. **Check environment variables**:

<Code lang="bash" code={`# Required for local development
echo $OPENAI_API_KEY`} />

3. **Restart local server**:

<Code lang="bash" code={`# Stop and restart
azion dev`} />


## 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](https://discord.gg/azion)

:::note
  When reporting issues, never include your Personal Token in logs or screenshots.
:::
---

## Next steps

   - [MCP Local Development](/en/documentation/devtools/mcp/local-development/)
   - [MCP Cache Testing](/en/documentation/devtools/mcp/cache-testing/)