Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-1913-1777010444034.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers common errors you might encounter when working with MCP servers and how to resolve them.

​
Connection Issues

​
Server fails to start or connect

  • Use absolute paths: Specify the full path to your server
    • ✅ Good: /Users/yourname/project/server.py
    • ❌ Bad: ./server.py or server.py
  • For uv projects: Use the --directory flag with absolute path 
    uv run --directory /Users/username/weather-mcp mcp.py
  • Test your command first: Run the server command manually in a terminal to verify it works before adding it to Inspector
  • For HTTP servers: Verify the URL is accessible
    • Test with curl or a browser first

​
Authentication Issues

​
Server fails to connect with authentication errors

If your server is failing to connect, first verify you’ve selected the correct authentication option:
  • No Authentication - Use this for local or development servers that don’t require authentication
  • Bearer Token - Use this if you already have an API token from the server
  • OAuth 2.0 - Use this for servers that require OAuth authorization flow

​
Getting 401 Unauthorized errors

If you’re seeing 401 Unauthorized errors when trying to connect to your server, this typically means the server requires authentication that hasn’t been set up yet. Solution:
  1. Change your authentication type to OAuth 2.0 in the server configuration
  2. Go through the OAuth authorization flow to obtain credentials
  3. Use the OAuth Debugger to troubleshoot any issues with the OAuth process
The OAuth Debugger helps you step through each part of the authorization process and identify where things might be going wrong.

​
Toggle shows a re-authentication error for an OAuth server

The enable/connect toggle on a server card or detail modal reuses existing credentials only. If your tokens are expired or missing, the toggle will report a re-authentication error rather than opening the OAuth consent screen. Solution: Use the Reconnect button on the server card or detail modal to start a full OAuth flow and obtain new credentials. The toggle is intentionally non-interactive for OAuth to avoid unexpected browser redirects.

​
Common Configuration Mistakes

  • Missing required environment variables
  • Incorrect transport type selection
  • Typos in server URLs or commands
  • Missing file permissions or executable flags

​
Getting Help

If you’re still experiencing issues:
  1. Check server documentation
    • Review the MCP server’s specific documentation
    • Look for known issues or troubleshooting guides
  2. Community support