# Troubleshooting

Common issues and solutions for MCP Gateway connections.

## Connection Issues

### Connection Failed

- Verify server URL is correct (including `https://`)
- Check authentication credentials are valid and not expired
- Enable popups for Vendia’s domain in browser settings
- Ensure the MCP server is online (check service status page)
- Test URL accessibility with curl or browser

### Server Not Listed After Connection

- Refresh the MCP Gateway page
- Check browser console for JavaScript errors
- Clear browser cache and try again
- Verify you’re in the correct **workspace**

## Authentication Issues

### OAuth Authorization Failed

- Enable popups for `vendia.com` in browser settings
- Grant all requested permissions during authorization
- If using app credentials, verify client ID and secret are correct
- Check external service status page for outages
- Try a different browser if issues persist

### API Key Authentication Not Working

- Verify API key is correct and hasn’t expired
- Check header names are exact (case-sensitive: `Authorization`, `X-API-Key`)
- Ensure header format matches service requirements (e.g., `Bearer token`)
- Test API key directly with curl or Postman outside Vendia
- Verify API key has necessary permissions for requested operations

## Server Access Issues

### Tools Not Appearing in AI Application

- Disconnect and reconnect your AI application to Vendia MCP Gateway
- Wait a few minutes for tool discovery to complete
- Verify connection shows as active in MCP Gateway
- Check AI application’s MCP settings and enabled servers
- Try disconnecting and reconnecting the server in MCP Gateway

### Queries Fail or Timeout

- Check external service status page for outages
- Verify query syntax matches service documentation
- Check for rate limits or quota exceeded errors
- Test with simpler queries to isolate issues
- Verify OAuth/API key permissions include requested data access

## Custom Server Issues

### Can’t Connect to Custom MCP Server

- Verify URL follows MCP specification format
- Ensure protocol is `https://` (not `http://`)
- Check server is publicly accessible via HTTPS
- Test server with MCP client tool first
- Verify SSL certificate is valid
- Check authentication method matches server requirements

## Getting Help

For additional support:

- Review [Connecting External MCP Servers](https://docs.vendia.com/platform/vendia-mcp-server/mcp-gateway/connecting-mcp-servers)
- Check [Authentication Methods](https://docs.vendia.com/platform/vendia-mcp-server/mcp-gateway/authentication)
- See [Use Cases](https://docs.vendia.com/platform/vendia-mcp-server/mcp-gateway/use-cases) for example queries
- Contact support: Free Tier via [contact form](https://www.vendia.com/contact-us/), Enterprise at [support@vendia.com](mailto:support@vendia.com)