Model Context Protocol (MCP) Development Tutorial: Building Production Enterprise Servers

The Missing Bridge Between Frontier LLMs and Enterprise Infrastructure

Large Language Models (LLMs) possess extraordinary reasoning capabilities, but in isolation, they are deaf, mute, and blind to your private corporate data. Until recently, connecting an LLM to external systems meant writing brittle, proprietary function-calling wrappers for OpenAI, separate adapters for Anthropic, and custom integrations for local models. Every tool integration was a bespoke, one-off glue code nightmare.

Anthropic's open-source Model Context Protocol (MCP) standardizes how AI agents discover, query, and execute capabilities across external data stores, internal APIs, and developer environments. Analogous to how the Language Server Protocol (LSP) standardized how IDEs communicate with programming language compilers, MCP creates a universal protocol for AI tool calling. At Betadrix, our AI development company engineers enterprise MCP infrastructure for autonomous workflows.

In this comprehensive architectural guide, we will build a production-grade, type-safe MCP server from the ground up using TypeScript. We will cover dual-transport mechanisms (stdio and Server-Sent Events), L7 Envoy load balancing, B2B API Gateway security with mutual TLS (mTLS), multi-tenant access controls, connection pooling, and real-world failure post-mortems. For dedicated infrastructure, explore our MCP development services and learn how we architect autonomous systems in our guide on agentic workflows for enterprise SaaS.

Core Primitives: Resources, Prompts, and Tools

The Model Context Protocol establishes three fundamental primitive abstractions between the AI Host (e.g., Claude Desktop, Cursor IDE, or an autonomous backend agent) and the MCP Server:

• Tools: Executable functions that the LLM can invoke to perform side effects or query dynamic external systems (e.g., executing a SQL query on a PostgreSQL database, dispatching a GitHub pull request, or triggering a Kubernetes rollout).
• Resources: Passive, readable data artifacts similar to REST GET endpoints (e.g., system log streams, database schema definitions, or documentation files) that provide context without executing actions.
• Prompts: Pre-engineered contextual templates that guide user interactions and structure agent reasoning for specific domain workflows.

Enterprise Architecture: L7 Load Balancing, Ingress, and B2B API Gateway

While local desktop tools communicate via standard I/O (stdio), enterprise agentic deployments run MCP servers as distributed microservices on Kubernetes clusters. Below is the production topology featuring an L7 Envoy Load Balancer and a B2B API Gateway managing secure agent interactions:

+-------------------------------------------------------------------------------+
|                        ENTERPRISE MCP SERVER TOPOLOGY                         |
+-------------------------------------------------------------------------------+
[AI Agent / LLM Client]  (Anthropic Claude 3.5 / OpenAI GPT-4o / Local vLLM)
       |
       | HTTPS / JSON-RPC 2.0 over SSE
       v
+-------------------------------------------------------------------------------+
| [B2B API Gateway] (Kong / Envoy / Apisix)                                     |
|  - Mutual TLS (mTLS) Termination & Client Certificate Verification            |
|  - Multi-Tenant Authentication (JWT / API Key Token Bucket Rate Limiting)     |
|  - Tenant Quota Enforcement & Header Injection (x-tenant-id, x-user-role)     |
+-------------------------------------------------------------------------------+
       |
       | Internal VPC Network
       v
+-------------------------------------------------------------------------------+
| [L7 Envoy Load Balancer]                                                      |
|  - Consistent Hash Ring Routing (by Tenant ID / Session ID)                   |
|  - HTTP/2 & Server-Sent Events (SSE) Long-Lived Connection Multiplexing       |
|  - Active Health Checking & Circuit Breaking (Max Pending Requests: 1024)     |
+-------------------------------------------------------------------------------+
       |
       +-----------------------+-----------------------+
       |                       |                       |
       v                       v                       v
+--------------------+  +--------------------+  +--------------------+
| [MCP Pod Replica 1]|  | [MCP Pod Replica 2]|  | [MCP Pod Replica 3]|
| - Fastify + SDK    |  | - Fastify + SDK    |  | - Fastify + SDK    |
| - Tool Sandbox     |  | - Tool Sandbox     |  | - Tool Sandbox     |
| - Tenant RLS SQL   |  | - Tenant RLS SQL   |  | - Tenant RLS SQL   |
+--------------------+  +--------------------+  +--------------------+
       |                       |                       |
       +-----------------------+-----------------------+
                               |
                               v
               +-------------------------------+
               | [Database Cluster / pgBouncer] |
               | - Multi-Tenant PostgreSQL 16   |
               | - Row-Level Security (RLS)    |
               +-------------------------------+

Multi-Tenant Isolation Strategy ("Tent")

In enterprise SaaS platforms, AI agents from different enterprise tenants must never access unauthorized data. We implement a three-tier multi-tenant isolation model:

1. Gateway Identity Propagation: The B2B API Gateway validates the tenant's mTLS certificate and Bearer token, extracting the tenant_id and claims, which are injected into signed downstream headers.
2. Context-Scoped MCP Transport: The MCP Server creates an isolated session context per tenant connection. Tool calls are strictly scoped to the tenant's authorized resource catalog.
3. PostgreSQL Row-Level Security (RLS): Database tool executions run through connection pools with active tenant session parameters: SET LOCAL app.current_tenant_id = 'tenant-xyz';. Even if an LLM is prompt-injected, the database engine physically blocks cross-tenant data retrieval.

Transport Protocols: stdio vs. Server-Sent Events (SSE)

Production Implementation: High-Throughput TypeScript MCP Server

Below is a production-tested implementation using Fastify and the official @modelcontextprotocol/sdk with multi-tenant context handling and pgBouncer connection pooling:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool
} from "@modelcontextprotocol/sdk/types.js";
import Fastify from "fastify";
import pg from "pg";
import { z } from "zod";

// Initialize PostgreSQL pool with pgBouncer transaction pooling
const dbPool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 5000,
});

// Define schemas with Zod
const QueryInputSchema = z.object({
  sql: z.string().min(1).max(5000),
  tenantId: z.string().uuid(),
});

// Configure MCP Server
const mcpServer = new Server(
  {
    name: "enterprise-tenant-data-service",
    version: "2.1.0",
  },
  {
    capabilities: {
      tools: {},
      resources: {},
    },
  }
);

// Expose tools
const DB_TOOL: Tool = {
  name: "execute_tenant_query",
  description: "Executes a secure read-only SQL query isolated to a specific tenant with RLS enforcement.",
  inputSchema: {
    type: "object",
    properties: {
      sql: { type: "string", description: "The SELECT query to execute." },
      tenantId: { type: "string", description: "The UUID of the tenant executing the query." },
    },
    required: ["sql", "tenantId"],
  },
};

mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [DB_TOOL],
}));

mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name !== "execute_tenant_query") {
    throw new Error(`Unknown tool: ${request.params.name}`);
  }

  const { sql, tenantId } = QueryInputSchema.parse(request.params.arguments);

  // Validate read-only SQL
  const sanitized = sql.trim().toLowerCase();
  if (!sanitized.startsWith("select") && !sanitized.startsWith("explain")) {
    throw new Error("Disallowed: Only SELECT or EXPLAIN statements are permitted.");
  }

  const client = await dbPool.connect();
  try {
    await client.query("BEGIN TRANSACTION READ ONLY;");
    // Set tenant session variable for Row-Level Security
    await client.query("SELECT set_config('app.current_tenant_id', $1, true);", [tenantId]);
    
    // Execute with 3000ms statement timeout
    await client.query("SET LOCAL statement_timeout = 3000;");
    const result = await client.query(sql);
    await client.query("COMMIT;");

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            rowCount: result.rowCount,
            rows: result.rows.slice(0, 100), // Enforce 100 row ceiling
          }, null, 2),
        },
      ],
    };
  } catch (err: any) {
    await client.query("ROLLBACK;");
    return {
      isError: true,
      content: [{ type: "text", text: `Database execution error: ${err.message}` }],
    };
  } finally {
    client.release();
  }
});

// Fastify HTTP Server for SSE Transport
const app = Fastify({ logger: true });

app.get("/mcp/sse", async (req, reply) => {
  const tenantId = req.headers["x-tenant-id"] as string;
  if (!tenantId) {
    return reply.status(401).send({ error: "Missing x-tenant-id header from API gateway" });
  }

  reply.raw.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    "Connection": "keep-alive",
    "X-Accel-Buffering": "no", // Disable Nginx proxy buffering
  });

  const transport = new SSEServerTransport("/mcp/messages", reply.raw);
  await mcpServer.connect(transport);
});

app.listen({ port: 8080, host: "0.0.0.0" }, () => {
  console.log("Enterprise MCP Server running on port 8080");
});

Real-World Failure Modes & Production Post-Mortems

1. ALB / Proxy Buffering Timeout: Cloud load balancers (such as AWS ALB) default to closing idle HTTP connections after 60 seconds. When an LLM model performs prolonged multi-step chain-of-thought reasoning before firing a tool, the ALB drops the SSE socket. Mitigation: Configure the MCP SSE transport to emit an empty comment heartbeat (: ping\n\n) every 15 seconds, and set ALB idle timeout to 300 seconds.
2. Unbounded Tool Payload Memory Explosion: When an agent queries a large database table without pagination, a 50MB JSON payload can cause the V8 JavaScript heap to exhaust its memory allocation, crashing the MCP pod. Mitigation: Enforce strict database limit wrappers (maximum 100 rows per query) and stream large dataset results into ephemeral S3 presigned URLs rather than passing raw text into LLM context.
3. Connection Pool Starvation Under Concurrency Spikes: If 50 agents execute slow analytics queries simultaneously, pgBouncer worker pools exhaust available sockets, blocking health check endpoints and causing Kubernetes to cycle pods into CrashLoopBackOff. Mitigation: Deploy dedicated connection pool partitions for AI agent tools with aggressive statement timeouts (3,000ms max).

Performance & Latency Benchmarks