Troubleshooting Common Issues

Find solutions to common problems and learn debugging techniques for MCP Server.

Common Errors

Authentication Errors

Error: 401 Unauthorized

Solution:

// Check your API key is correct
console.log('API Key:', process.env.MCP_API_KEY?.substring(0, 10) + '...');

// Ensure it's properly formatted
if (!process.env.MCP_API_KEY?.startsWith('mcp_')) {
  throw new Error('Invalid API key format');
}

Rate Limiting

Error: 429 Too Many Requests

Solution:

import pRetry from 'p-retry';

const result = await pRetry(
  async () => {
    return await client.tools.execute({ tool: 'api-call' });
  },
  {
    retries: 3,
    onFailedAttempt: error => {
      if (error.code === 429) {
        const retryAfter = error.response?.headers['retry-after'];
        console.log(Rate limited. Retry after ${retryAfter}s);
      }
    },
  }
);

Connection Timeouts

Error: Request timeout

Solution:

const client = new MCPClient({
  apiKey: process.env.MCP_API_KEY,
  timeout: 30000, // Increase timeout to 30 seconds
  retries: 3,
});

Invalid Parameters

Error: 400 Bad Request - Invalid parameters

Solution:

// Validate parameters before sending
function validateParams(params: any, schema: any) {
  // Use a validation library like Zod
  const result = schema.safeParse(params);
  if (!result.success) {
    console.error('Validation errors:', result.error);
    throw new Error('Invalid parameters');
  }
  return result.data;
}

const params = validateParams(userInput, toolSchema);
await client.tools.execute({ tool: 'database-query', params });

Debugging Techniques

Enable Debug Logging

const client = new MCPClient({
  apiKey: process.env.MCP_API_KEY,
  debug: true, // Enable detailed logging
  logger: {
    level: 'debug',
    transport: console,
  },
});

Inspect Network Requests

client.on('request', (config) => {
  console.log('Request:', {
    url: config.url,
    method: config.method,
    headers: config.headers,
  });
});

client.on('response', (response) => {
  console.log('Response:', {
    status: response.status,
    data: response.data,
  });
});

Health Checks

// Check API health
const health = await client.health.check();
console.log('API Status:', health.status);
console.log('Latency:', health.latency, 'ms');

// Check specific services
const dbHealth = await client.databases.health();
console.log('Database Status:', dbHealth.status);

Performance Issues

Slow Queries

Problem: Database queries taking too long

Solution:

// Add query timeout
await client.databases.query({
  sql: 'SELECT * FROM large_table',
  timeout: 5000, // 5 second timeout
});

// Use query explain to analyze
const explain = await client.databases.explain({
  sql: 'SELECT * FROM users WHERE email = ?',
  params: ['user@example.com'],
});
console.log('Query plan:', explain);

Memory Leaks

Problem: Application memory usage increasing over time

Solution:

// Close connections when done
await client.databases.disconnect();

// Implement connection pooling
const pool = await client.databases.createPool({
  min: 2,
  max: 10,
  acquireTimeoutMillis: 30000,
  idleTimeoutMillis: 30000,
});

// Use the pool
const result = await pool.query('SELECT * FROM users');

// Clean up
await pool.end();

Integration Issues

Tool Not Found

Error: Tool 'custom-tool' not found

Solution:

// List all available tools
const tools = await client.tools.list();
console.log('Available tools:', tools.map(t => t.name));

// Register custom tool if needed
await client.tools.register({
  name: 'custom-tool',
  description: 'My custom tool',
  parameters: { /* ... */ },
  handler: async (params) => { /* ... */ },
});

API Version Mismatch

Error: Unsupported API version

Solution:

const client = new MCPClient({
  apiKey: process.env.MCP_API_KEY,
  apiVersion: 'v1', // Specify version explicitly
});

Getting Help

Check Status Page

Visit status.mcpserver.design for service status and incidents.

Community Support

Join our Discord: discord.gg/mcpserver

GitHub Discussions: github.com/mcpserver/discussions

Stack Overflow: Tag your questions with mcp-server

Contact Support

For urgent issues:

Email: support@mcpserver.design

Response time: < 24 hours (< 4 hours for Enterprise)

Reporting Bugs

When reporting bugs, include:

1. SDK version

2. Error message and stack trace

3. Minimal reproduction code

4. Expected vs actual behavior

5. Environment details (OS, Node version, etc.)

Next Steps

Getting Started

Authentication & Security

Scaling Your Application