MCP Implementation Guide - AI-Optimized Technical Reference

Implementation Time Requirements

Approach	Working Demo	Production Ready	Maintenance Effort	Failure Point
Copy Official Examples	30 minutes	2-4 weeks	Low	Authentication
Fork & Modify	1-2 hours	1-3 weeks	Medium	Code understanding
TypeScript SDK	2-4 hours	2-6 weeks	Medium	Error handling
Python SDK	3-6 hours	3-8 weeks	Medium-High	Async complexity
Build from Scratch	1-2 weeks	2-6 months	High	Everything

Critical Configuration

Environment Requirements

• Node.js: 18.19.x or latest 20.x patches (20.x has stdio transport issues causing random disconnects)
• Python: 3.11.x (3.12+ breaks MCP SDK dependencies)
• Claude Desktop: Required (web version doesn't support MCP)

Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• CRITICAL: Use absolute paths only, not relative paths

Database Integration (Most Common Use Case)

Connection Setup

-- Create read-only user (production requirement)
CREATE USER claude_readonly WITH PASSWORD 'secure_password';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

Common Database Errors and Solutions

• FATAL: password authentication failed → Wrong credentials
• FATAL: database does not exist → Database name typo
• ECONNREFUSED 127.0.0.1:5432 → PostgreSQL not running or wrong port
• FATAL: too many clients already → Need connection pooling

Connection Pooling (Production Requirement)

const pool = new pg.Pool({
  max: 10,  // Maximum connections
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
});

Security Requirements

Input Validation Patterns

// Table name validation (prevent SQL injection)
const validateTableName = (tableName: string): boolean => {
  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName);
};

// Prevent memory exhaustion
const validateLimit = (limit: number): boolean => {
  return limit > 0 && limit <= 1000;
};

Rate Limiting (API Protection)

class RateLimiter {
  private requests: number[] = [];
  
  canMakeRequest(): boolean {
    const now = Date.now();
    const oneMinuteAgo = now - 60000;
    this.requests = this.requests.filter(time => time > oneMinuteAgo);
    
    if (this.requests.length >= 100) return false;  // 100 req/min max
    this.requests.push(now);
    return true;
  }
}

Error Handling That Actually Helps Users

Bad vs Good Error Messages

// Bad - Useless to users
catch (error) {
  return { error: "Something went wrong" };
}

// Good - Actionable information
catch (error) {
  if (error.code === 'ECONNREFUSED') {
    return { 
      error: "Database connection failed. Check if PostgreSQL is running.",
      troubleshooting: "Try: pg_ctl status"
    };
  }
  
  if (error.code === '42P01') {  // PostgreSQL table doesn't exist
    return {
      error: `Table '${tableName}' not found. Available tables: ${availableTables.join(', ')}`,
      suggestion: "Check table name spelling or permissions"
    };
  }
}

Performance Thresholds and Limits

Connection Limits

• Development: 5 connections maximum
• Production: 20 connections maximum
• Timeout: 2 seconds connection, 30 seconds idle

Query Limits

• Row limit: 1000 rows maximum (prevent memory issues)
• API calls: 100 requests per minute (prevent rate limiting)
• Cache TTL: 5 minutes for reference data

Common Failure Scenarios

Setup Failures

1. "MCP server not found" → Wrong file paths in config (use absolute paths)
2. "Connection refused" → Server crashed on startup (run manually to see errors)
3. "Permission denied" → File/database permissions issues
4. "Invalid JSON-RPC" → Malformed responses (usually undefined instead of null)
5. Silent failures → Server missing tools/list method implementation

Production Failures

• UI breaks at 1000+ spans → Makes debugging large distributed transactions impossible
• Memory exhaustion → From unlimited query results
• Authentication failures → OAuth token expiration without refresh
• Rate limiting bans → From excessive API calls during analysis

Debugging Tools and Commands

Essential Testing Sequence

1. Protocol testing: npx @modelcontextprotocol/inspector stdio path/to/server
2. Manual server testing: node /path/to/your/server.js
3. HTTP testing: curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' SERVER_URL
4. User experience testing: Claude Desktop (test last)

Health Check Implementation

server.tool('health_check', {}, async () => {
  const checks = [];
  
  // Test database
  try {
    await pool.query('SELECT 1');
    checks.push({ name: 'database', status: 'ok' });
  } catch (error) {
    checks.push({ name: 'database', status: 'fail', error: error.message });
  }
  
  return {
    status: checks.every(check => check.status === 'ok') ? 'healthy' : 'unhealthy',
    checks: checks,
    timestamp: new Date().toISOString()
  };
});

Deployment Requirements

Process Management

// PM2 configuration
module.exports = {
  apps: [{
    name: 'mcp-server',
    script: 'dist/index.js',
    instances: 1,
    autorestart: true,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      LOG_LEVEL: 'info'
    }
  }]
};

Docker Configuration

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
USER node
CMD ["npm", "start"]

Architecture Decision Criteria

When to Use Multiple Servers vs Single Server

Use multiple specialized servers for:

• Different data domains (customer data vs monitoring)
• Different security requirements (public vs internal)
• Different teams maintaining them
• When current server becomes kitchen sink

Scale existing server for:

• Adding similar data sources
• Minor feature additions
• Good performance needing higher availability

Critical Operational Intelligence

What Official Documentation Doesn't Tell You

• Node.js 20.x versions have random stdio disconnect issues
• Python 3.12+ breaks MCP SDK dependencies silently
• "Universal MCP platforms" always fail from complexity
• Teams spend months planning "enterprise architecture" and never ship
• 30-minute demos often run in production longer than planned

Resource Investment Reality

• Prototype to production: 2-6 weeks additional development
• Maintenance overhead: Medium for TypeScript, High for Python
• Team knowledge transfer: 2-3 weeks for complex servers
• Security audit requirements: Plan additional 1-2 weeks

Success Metrics That Matter

• Time saved on specific tasks (measurable)
• Continued usage after first week (sustainability indicator)
• Error rate reduction in production workflows
• NOT generic "productivity improvements" (meaningless)

Essential Resources

Must-Have Tools

• MCP Inspector - Protocol debugging (essential)
• TypeScript SDK - Most mature SDK
• Official Examples - Working patterns
• Claude Desktop - Required for testing

Transport Recommendations

• STDIO: Local development (simpler debugging)
• HTTP: Production deployment (standard web service patterns)

Breaking Points and Limits

• Query complexity: UI becomes unusable beyond 1000 database rows
• API rate limits: GitHub allows 5000 req/hour, Claude can exhaust in minutes
• Connection pools: Exhaustion causes cascading failures
• Memory usage: Unlimited query results crash servers