Building MCP Servers

An MCP server exposes 'tools' that Claude can call. Each tool has a name, description, and input schema.

The communication happens over stdio or HTTP, using JSON-RPC 2.0 protocol.

Security is built-in: MCP servers can implement authentication, rate limiting, and access control.

// Basic MCP server structure
import { Server } from "@modelcontextprotocol/sdk/server";

const server = new Server({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Define a tool
server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "get_user",
    description: "Fetch user by ID",
    inputSchema: {
      type: "object",
      properties: {
        userId: { type: "string" }
      },
      required: ["userId"]
    }
  }]
}));

We'll use the official MCP SDK for TypeScript. The SDK handles protocol details so you can focus on business logic.

You'll need Node.js 18+, TypeScript, and the MCP SDK packages.

# Create project
mkdir my-mcp-server && cd my-mcp-server
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

# Initialize TypeScript
npx tsc --init

Let's build a simple tool that queries a database. We'll create a tool that fetches customer information.

Every tool needs: a unique name, clear description, and a JSON Schema for inputs.

The description is crucial - Claude uses it to understand when to call your tool.

import { Server } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";

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

server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_customer") {
    const customer = await db.customers.findById(args.customerId);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(customer, null, 2)
      }]
    };
  }
});

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

Production MCP servers must handle authentication securely. Never expose credentials in tool responses.

Common patterns: environment variables for secrets, OAuth flows for user context, API keys for service-to-service auth.

Consider using a secrets manager like AWS Secrets Manager or HashiCorp Vault in production.

Robust error handling is essential. Return clear error messages that help Claude (and users) understand what went wrong.

Use Zod or similar libraries to validate inputs before processing.

Log errors for debugging, but be careful not to expose sensitive information.

import { z } from "zod";

const GetCustomerSchema = z.object({
  customerId: z.string().uuid(),
});

server.setRequestHandler("tools/call", async (request) => {
  try {
    const args = GetCustomerSchema.parse(request.params.arguments);
    const customer = await db.customers.findById(args.customerId);

    if (!customer) {
      return {
        isError: true,
        content: [{ type: "text", text: "Customer not found" }]
      };
    }

    return { content: [{ type: "text", text: JSON.stringify(customer) }] };
  } catch (error) {
    return {
      isError: true,
      content: [{ type: "text", text: `Validation error: ${error.message}` }]
    };
  }
});

Test your MCP server locally before deploying. The MCP Inspector tool helps debug communication.

Write unit tests for your tool handlers. Mock external services for reliable testing.

Integration test with Claude Code to ensure tools work as expected in practice.

MCP servers can run locally (stdio) or as HTTP services. Choose based on your use case.

For team usage, deploy as a containerized service with proper monitoring and logging.

Consider serverless deployment (AWS Lambda, Cloudflare Workers) for simple, stateless tools.

Always validate and sanitize inputs. Never trust data from tool calls.

Implement rate limiting to prevent abuse. Log all tool invocations for audit trails.

Use least-privilege access: only grant the permissions your tools actually need.

Regular security reviews are essential, especially for tools that modify data.

Database query tools: Let Claude analyze data without direct SQL access.

API wrappers: Connect to Salesforce, HubSpot, or internal APIs.

Document processors: Extract information from PDFs, spreadsheets, or images.

Workflow triggers: Start CI/CD pipelines, create tickets, or send notifications.