Common MCP Errors and How to Fix Them: Complete Troubleshooting Guide With Code Examples

// Error in Claude Desktop logs:
// "Failed to connect to MCP server: Connection refused"
// or
// "MCP server process exited with code 1"

// Root cause 1: Wrong path in Claude Desktop config
// Fix: Check claude_desktop_config.json

// WRONG — relative path
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

// CORRECT — absolute path required
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/Users/yourname/projects/mcp-server/dist/server.js"]
    }
  }
}

// Root cause 2: TypeScript source not compiled
// The config points to .ts file instead of compiled .js
// Fix: compile first, point to dist/ directory
// package.json:
{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

// Root cause 3: Missing shebang for executable scripts
// If using npx to run the server:
// Add to top of your server.ts:
// #!/usr/bin/env node

// Error: "Invalid tool definition: schema validation failed"
// or: Tool appears in list but calling it returns error

// WRONG — missing required fields in schema
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// WRONG schema — properties not defined correctly
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "search_web",
    description: "Search the web",
    inputSchema: {
      type: "object",
      // MISSING: properties definition
      // MISSING: required array
    }
  }]
}));

// CORRECT schema — complete and valid
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "search_web",
      description: "Search the web for current information",
      inputSchema: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "The search query to execute"
          },
          num_results: {
            type: "number",
            description: "Number of results to return (1-10)",
            default: 5
          }
        },
        required: ["query"]  // List all required properties
      }
    }
  ]
}));

// CORRECT tool call handler with proper error handling
import {
  ListToolsRequestSchema,
  CallToolRequestSchema,
  ErrorCode,
  McpError
} from "@modelcontextprotocol/sdk/types.js";

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === "search_web") {
    // Validate args before using them
    if (!args || typeof args.query !== "string") {
      throw new McpError(
        ErrorCode.InvalidParams,
        "query parameter is required and must be a string"
      );
    }
    
    try {
      const results = await performSearch(args.query, args.num_results || 5);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(results, null, 2)
          }
        ]
      };
    } catch (error) {
      // Proper error propagation
      throw new McpError(
        ErrorCode.InternalError,
        `Search failed: ${error instanceof Error ? error.message : "Unknown error"}`
      );
    }
  }
  
  throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
});

// Error: Tool executes but returns nothing useful
// Root cause: content array format incorrect

// WRONG — returning plain string
return {
  result: "Here are the search results..."
  // MCP expects 'content' array, not 'result'
};

// WRONG — content items missing 'type' field
return {
  content: [
    { text: "Here are the results" }  // Missing type field
  ]
};

// CORRECT — proper content array format
return {
  content: [
    {
      type: "text",  // Required: 'text' | 'image' | 'resource'
      text: "Here are the search results:\n\n1. Result one\n2. Result two"
    }
  ]
  // isError field: omit for success, set to true for errors
};

// For image content:
return {
  content: [
    {
      type: "image",
      data: base64EncodedImageData,  // Base64 encoded
      mimeType: "image/png"           // Required for images
    }
  ]
};

// For resource content (files, URLs):
return {
  content: [
    {
      type: "resource",
      resource: {
        uri:      "file:///path/to/file.txt",
        mimeType: "text/plain",
        text:     fileContents  // For text resources
      }
    }
  ]
};

// Error: API keys and environment variables undefined in MCP server
// Root cause: MCP servers launched by Claude Desktop do not inherit shell env

// WRONG — relying on process.env from shell profile
// Your .env or shell config does not apply to MCP server process

// CORRECT — pass env vars explicitly in Claude Desktop config
{
  "mcpServers": {
    "my-api-server": {
      "command": "node",
      "args": ["/path/to/dist/server.js"],
      "env": {
        "API_KEY":          "your-actual-api-key-here",
        "DATABASE_URL":     "postgresql://localhost:5432/mydb",
        "LOG_LEVEL":        "info"
      }
    }
  }
}

// For sensitive keys: use a secrets manager and fetch at startup
// server.ts — fetch secrets before server starts
async function loadSecrets() {
  // Option 1: Read from a local secrets file not in source control
  const secrets = JSON.parse(
    await fs.readFile(path.join(process.env.HOME!, '.mcp-secrets.json'), 'utf-8')
  );
  process.env.API_KEY = secrets.apiKey;
}

async function main() {
  await loadSecrets();
  const transport = new StdioServerTransport();
  await server.connect(transport);
}
main();

// Complete MCP server with all error handling patterns applied
// Copy this as a starting template to avoid common errors

import { Server }              from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ErrorCode,
  ListToolsRequestSchema,
  McpError,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "example-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Tool definitions
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_weather",
      description: "Get current weather for a city",
      inputSchema: {
        type: "object" as const,
        properties: {
          city: {
            type: "string",
            description: "City name to get weather for"
          },
          units: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            description: "Temperature units",
            default: "celsius"
          }
        },
        required: ["city"]
      }
    }
  ]
}));

// Tool execution with complete error handling
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_weather") {
    // Input validation
    if (!args?.city || typeof args.city !== "string") {
      throw new McpError(ErrorCode.InvalidParams, "city is required");
    }
    
    try {
      const data = await fetchWeather(args.city, args.units as string || "celsius");
      return {
        content: [{ type: "text" as const, text: formatWeatherResponse(data) }]
      };
    } catch (err) {
      // Return error in isError format rather than throwing
      // This allows Claude to handle the error gracefully
      return {
        content: [{
          type: "text" as const,
          text: `Failed to fetch weather: ${err instanceof Error ? err.message : "Unknown error"}`
        }],
        isError: true
      };
    }
  }
  
  throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // MCP servers should NOT console.log — it corrupts the stdio protocol
  // Use console.error for debug output (goes to stderr, not stdout)
  console.error("Server started");
}

main().catch(console.error);