Model Context Protocol: The Complete Developer Guide 2025

Core Components

┌─────────────────────────────────────────────────────────┐
│                    AI Application                       │
│  (ChatGPT, Claude, Custom App, IDE Extension, etc.)    │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ MCP Client Library
                     │
┌────────────────────▼────────────────────────────────────┐
│                  MCP Protocol Layer                     │
│  • Authentication (OAuth, API Keys, JWT)               │
│  • Request/Response Handling                           │
│  • Error Management                                    │
│  • Rate Limiting                                       │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        │            │            │
┌───────▼──────┐ ┌──▼──────┐ ┌──▼──────────┐
│ MCP Server 1 │ │ MCP     │ │ MCP Server  │
│ (Database)   │ │ Server 2│ │ 3 (API)     │
└───────┬──────┘ └──┬──────┘ └──┬──────────┘
        │           │            │
┌───────▼──────┐ ┌──▼──────┐ ┌──▼──────────┐
│ PostgreSQL   │ │ Files   │ │ Salesforce  │
│ Database     │ │ System  │ │ API         │
└──────────────┘ └─────────┘ └─────────────┘

Real-World Example: Database MCP Server

Let's build a complete MCP server that connects to a PostgreSQL database and exposes customer data to AI applications:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { Pool } from 'pg';

// Database connection
const pool = new Pool({
  host: process.env.DB_HOST,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  ssl: { rejectUnauthorized: false }
});

// Initialize MCP server
const server = new Server(
  {
    name: 'customer-database-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
      resources: {},
    },
  }
);

// Tool: Search customers
server.setRequestHandler('tools/list', async () => {
  return {
    tools: [
      {
        name: 'search_customers',
        description: 'Search for customers by name, email, or ID',
        inputSchema: {
          type: 'object',
          properties: {
            query: {
              type: 'string',
              description: 'Search query (name, email, or ID)'
            },
            limit: {
              type: 'number',
              description: 'Maximum number of results',
              default: 10
            }
          },
          required: ['query']
        }
      },
      {
        name: 'get_customer_orders',
        description: 'Get all orders for a specific customer',
        inputSchema: {
          type: 'object',
          properties: {
            customer_id: {
              type: 'string',
              description: 'Customer ID'
            }
          },
          required: ['customer_id']
        }
      }
    ]
  };
});

// Tool implementation: Search customers
server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'search_customers') {
    const { query, limit = 10 } = request.params.arguments;
    
    try {
      const result = await pool.query(
        `SELECT id, name, email, created_at, total_spent 
         FROM customers 
         WHERE name ILIKE $1 OR email ILIKE $1 
         LIMIT $2`,
        [`%${query}%`, limit]
      );
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result.rows, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }
  
  if (request.params.name === 'get_customer_orders') {
    const { customer_id } = request.params.arguments;
    
    try {
      const result = await pool.query(
        `SELECT o.id, o.order_date, o.total, o.status,
                json_agg(json_build_object(
                  'product', oi.product_name,
                  'quantity', oi.quantity,
                  'price', oi.price
                )) as items
         FROM orders o
         JOIN order_items oi ON o.id = oi.order_id
         WHERE o.customer_id = $1
         GROUP BY o.id
         ORDER BY o.order_date DESC`,
        [customer_id]
      );
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result.rows, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }
  
  throw new Error(`Unknown tool: ${request.params.name}`);
});

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.log('Customer Database MCP Server running');
}

main().catch(console.error);