Model Context Protocol (MCP): The Complete Guide to AI Tool Integration in 2026

┌─────────────────────────────────────────────┐
│              MCP Host Application            │
│  (Claude Desktop, IDE, Custom App)          │
│                                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │ MCP      │ │ MCP      │ │ MCP      │   │
│  │ Client 1 │ │ Client 2 │ │ Client 3 │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘   │
└───────┼────────────┼────────────┼──────────┘
        │            │            │
   ┌────▼─────┐ ┌────▼─────┐ ┌───▼──────┐
   │ MCP      │ │ MCP      │ │ MCP      │
   │ Server A │ │ Server B │ │ Server C │
   │ (Files)  │ │ (DB)     │ │ (API)    │
   └──────────┘ └──────────┘ └──────────┘

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

typescript
const server = new McpServer({
  name: "my-api-server",
  version: "1.0.0",
});

// Expose via HTTP
app.post("/mcp", async (req, res) => {
  const result = await server.handleRequest(req.body);
  res.json(result);
});

bash
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod

typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "customer-data",
  version: "1.0.0",
});

// Define a tool for searching customers
server.tool(
  "search_customers",
  "Search for customers by name, email, or account ID",
  {
    query: z.string().describe("Search query"),
    limit: z.number().default(10).describe("Max results to return"),
  },
  async ({ query, limit }) => {
    const customers = await db.customers.search(query, limit);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(customers, null, 2),
      }],
    };
  }
);

typescript
// Expose customer data as readable resources
server.resource(
  "customer",
  "customer://{customerId}",
  async (uri) => {
    const id = uri.pathname.split("/").pop();
    const customer = await db.customers.findById(id);
    return {
      contents: [{
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify(customer),
      }],
    };
  }
);

typescript
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await server.connect(transport);

typescript
server.tool(
  "query_database",
  "Execute a read-only SQL query against the database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Security: Only allow SELECT statements
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries allowed" }],
        isError: true,
      };
    }

const result = await pool.query(sql);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(result.rows, null, 2),
      }],
    };
  }
);

typescript
server.tool(
  "get_deals",
  "Get active deals from the CRM pipeline",
  {
    stage: z.enum(["prospecting", "qualification", "proposal", "closed-won"]),
    limit: z.number().default(20),
  },
  async ({ stage, limit }) => {
    const deals = await hubspot.deals.getAll({
      filterGroups: [{
        filters: [{ propertyName: "dealstage", operator: "EQ", value: stage }],
      }],
      limit,
    });
    return {
      content: [{ type: "text", text: JSON.stringify(deals, null, 2) }],
    };
  }
);

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects/my-app"
      ]
    }
  }
}

typescript
// BAD: Full database access
server.tool("execute_sql", "Run any SQL query", ...);

// GOOD: Scoped, read-only operations
server.tool("search_customers", "Search customers by name", ...);
server.tool("get_order_status", "Check order status by ID", ...);

typescript
const server = new McpServer({
  name: "secure-api",
  version: "1.0.0",
  auth: {
    type: "oauth2",
    authorizationUrl: "https://auth.example.com/authorize",
    tokenUrl: "https://auth.example.com/token",
    scopes: ["read:customers", "write:orders"],
  },
});

typescript
server.tool(
  "get_customer",
  "Get customer by ID",
  {
    customerId: z.string()
      .regex(/^cust_[a-zA-Z0-9]{20}$/)
      .describe("Customer ID in format cust_xxxxx"),
  },
  async ({ customerId }) => {
    // ID is already validated by Zod schema
    const customer = await db.customers.findById(customerId);
    if (!customer) {
      return {
        content: [{ type: "text", text: "Customer not found" }],
        isError: true,
      };
    }
    return {
      content: [{ type: "text", text: JSON.stringify(customer) }],
    };
  }
);

typescript
const originalTool = server.tool.bind(server);
server.tool = (name, description, schema, handler) => {
  return originalTool(name, description, schema, async (args) => {
    // Log the tool call
    await auditLog.write({
      tool: name,
      args,
      timestamp: new Date().toISOString(),
      userId: getCurrentUserId(),
    });
    return handler(args);
  });
};

typescript
import { RateLimiter } from "limiter";

const limiter = new RateLimiter({
  tokensPerInterval: 100,
  interval: "minute",
});

// Apply to tool handler
async function rateLimitedHandler(args) {
  const hasTokens = await limiter.tryRemoveTokens(1);
  if (!hasTokens) {
    return {
      content: [{ type: "text", text: "Rate limit exceeded. Try again shortly." }],
      isError: true,
    };
  }
  // ... actual handler
}

┌──────────┐     ┌────────────┐     ┌──────────────┐
│ AI Agent │────▶│ MCP Gateway│────▶│ MCP Server A │
│          │     │ (Auth,     │────▶│ MCP Server B │
│          │     │  Logging,  │────▶│ MCP Server C │
│          │     │  Rate Lim) │     └──────────────┘
└──────────┘     └────────────┘

┌─────────────────────────────┐
│ Kubernetes Pod              │
│ ┌──────────┐ ┌────────────┐ │
│ │ Your API │ │ MCP Sidecar│ │
│ │ Service  │◀│ Server     │ │
│ └──────────┘ └────────────┘ │
└─────────────────────────────┘

typescript
// Vercel/AWS Lambda compatible
export default async function handler(req, res) {
  const server = new McpServer({ name: "serverless-mcp", version: "1.0.0" });
  // Register tools...
  const result = await server.handleRequest(req.body);
  res.json(result);
}