Common MCP Integration Problems and Fixes

Server Will Not Start

Command not found

The MCP client tries to launch your server with the configured command but the executable is not on the PATH. This happens most often with Python servers when the virtual environment is not activated, or with Node servers when npx is not installed.

Fix: Use absolute paths in your MCP configuration. Instead of "command": "python", use "command": "/home/user/.venv/bin/python". For Node servers, use "command": "/usr/local/bin/node" or the full path to your node installation. Test by running the exact command from a clean terminal session (not one with your development environment loaded).

Missing dependencies

The server process starts but crashes immediately because an import or require fails. This happens when the server was developed in a virtual environment that has packages the global Python does not, or when node_modules were not installed in the deployment directory.

Fix: Run the server manually from the command line with the same command and working directory the client uses. Watch for import errors in the output. Install missing packages, or update the configuration to use the correct environment that has all dependencies.

Port already in use

For HTTP servers, the configured port is already occupied by another process. The server fails to bind and exits.

Fix: Check what is using the port with lsof -i :8080 (or the relevant port number). Either stop the conflicting process or change your server to use a different port.

Permission denied

The server needs access to a file, directory, or resource that the current user cannot access. This is common when the client runs under a restricted user or when the server needs to read files outside the project directory.

Fix: Check file permissions on the server script and any resources it accesses. For stdio servers, the server runs as the same user who started the client, so verify that user has the required access.

Server Starts but Tools Are Not Discovered

Registration exception swallowed silently

A bug in one tool's registration code (wrong type hint, invalid schema, exception during decoration) can prevent that tool and all subsequent tools from registering. Some SDKs log the error; others fail silently.

Fix: Add logging before and after each tool registration. Use the MCP Inspector to see which tools appear. If some tools are missing, the problem is in the registration code for the first missing tool. Check for type annotation errors, missing imports in decorator functions, and exceptions thrown during initialization.

Protocol version mismatch

The client and server are using incompatible versions of the MCP protocol. The initialization handshake fails, and the client does not request the tool list.

Fix: Update both the MCP SDK in your server and the AI client to their latest versions. The MCP specification is backward-compatible within major versions, so keeping both sides current prevents most version issues.

stdout pollution

For stdio servers, any output to stdout that is not a valid JSON-RPC message corrupts the protocol stream. Print statements, logging to stdout, or third-party libraries that write to stdout can cause the client to fail during initialization.

Fix: Remove all print statements from your server. Configure logging to write to stderr, not stdout. Check any imported libraries for unexpected stdout output. Use the MCP Inspector in verbose mode to see the raw messages and identify non-protocol output.

Tools Discovered but Invocations Fail

Parameter type mismatches

The model sends a parameter as a string, but your handler expects an integer (or vice versa). This happens when the JSON schema for the tool does not match the handler's type expectations, or when the model interprets the schema differently than you intended.

Fix: Add explicit type conversion at the top of your handler function. Do not assume the model will always send the correct type. Parse strings to integers where needed, handle both string and numeric inputs for number fields, and provide defaults for optional parameters that arrive as null.

Missing required parameters

The model omits a required parameter because the tool description did not make it clear that the parameter is mandatory, or because the model decided it could infer a default.

Fix: Make required parameters obvious in the description. Use the "required" field in your JSON schema. Give optional parameters explicit defaults in your handler so missing values do not cause crashes.

Handler exceptions

Your tool handler throws an uncaught exception. The MCP SDK returns a generic error to the client, and the model sees an unhelpful "internal error" message.

Fix: Wrap your handler logic in try/except (Python) or try/catch (TypeScript). Return descriptive error messages as normal tool results rather than letting exceptions propagate. The model can use a clear error message to adjust its approach, but it cannot do anything useful with a generic protocol error.

Tools Work in Inspector but Not in the Client

Environment differences

The Inspector runs your server from your development terminal, which has your PATH, virtual environment, and environment variables. The AI client starts the server in a different environment, possibly without these settings.

Fix: Specify all required environment variables in the MCP configuration's env field. Use absolute paths for the command and all file references. Do not rely on shell profile settings (.bashrc, .zshrc) because the client may not load them when starting the subprocess.

Working directory differences

Your server assumes it runs from the project root, but the client starts it from a different working directory. File paths that work from one directory fail from another.

Fix: Set the working directory explicitly in the MCP configuration using the cwd field. Or design your server to work from any directory by using absolute paths or resolving paths relative to the script location rather than the current directory.

Timeout issues

A tool that works fine interactively takes too long when called by the AI client. The client has a timeout (typically 30 to 60 seconds) and kills the request before the server responds.

Fix: Optimize slow operations. Add pagination for large result sets. Cache expensive computations. If the operation is inherently slow (like a complex analysis), return partial results quickly and provide a way to request more detail in a follow-up call.

Authentication Issues

Invalid or expired credentials

The API key or OAuth token in the configuration is wrong, expired, or revoked. The server rejects the request with a 401 or 403 status.

Fix: Verify the credentials by testing them directly with curl or a simple HTTP client. Check for leading/trailing whitespace in the configuration (a common issue when copying keys). If using environment variables, verify they are set in the environment the client uses.

Wrong Authorization header format

The server expects Bearer TOKEN but the configuration sends just the token, or vice versa. Small formatting differences in the Authorization header cause authentication to fail even with correct credentials.

Fix: Match the Authorization header format exactly to what the server expects. Most MCP servers expect "Authorization": "Bearer your-key". Check the server documentation for the expected format.