How to Build an MCP Server

// Client → Server: Tool call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_documents",
    "arguments": { "query": "authentication best practices" }
  }
}

// Server → Client: Result
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Found 3 relevant documents..." }
    ]
  }
}

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

async function main(): Promise<void> {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running on stdio");
}

main().catch(console.error);

import { z } from "zod";

// Define a tool that searches a knowledge base
server.tool(
  "search_knowledge_base",
  "Search the documentation knowledge base for relevant articles. Returns matched documents with relevance scores.",
  {
    query: z.string().describe("The search query"),
    limit: z.number().optional().default(5).describe("Max results to return"),
    category: z
      .enum(["guides", "api", "tutorials"])
      .optional()
      .describe("Filter by content category"),
  },
  async ({ query, limit, category }) => {
    try {
      const results = await searchDocuments(query, { limit, category });

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(results, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Search failed: ${error instanceof Error ? error.message : "Unknown error"}`,
          },
        ],
        isError: true,
      };
    }
  }
);

// Static resource — content is known at registration time
server.resource(
  "app-config",
  "config://app/settings",
  "Current application configuration and feature flags",
  async () => ({
    contents: [
      {
        uri: "config://app/settings",
        mimeType: "application/json",
        text: JSON.stringify({
          features: { darkMode: true, betaSearch: false },
          limits: { maxUploadSize: "10MB", rateLimit: 100 },
        }),
      },
    ],
  })
);

// Dynamic resource template — URI contains a parameter
server.resource(
  "user-profile",
  "users://{userId}/profile",
  "User profile data including preferences and history",
  async (uri) => {
    const userId = uri.pathname.split("/")[1];
    const profile = await fetchUserProfile(userId);

    return {
      contents: [
        {
          uri: uri.toString(),
          mimeType: "application/json",
          text: JSON.stringify(profile),
        },
      ],
    };
  }
);

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

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

import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID(),
  });
  await server.connect(transport);
  await transport.handleRequest(req, res);
});

app.listen(3001, () => {
  console.error("MCP HTTP server on port 3001");
});

server.tool(
  "delete_document",
  "Permanently delete a document by ID",
  { documentId: z.string().uuid() },
  async ({ documentId }) => {
    // Verify the document exists and the caller has permission
    const doc = await db.documents.findById(documentId);
    if (!doc) {
      return {
        content: [{ type: "text", text: "Document not found" }],
        isError: true,
      };
    }

    if (doc.isProtected) {
      return {
        content: [{ type: "text", text: "Cannot delete protected documents" }],
        isError: true,
      };
    }

    await db.documents.delete(documentId);
    return {
      content: [{ type: "text", text: `Deleted document ${documentId}` }],
    };
  }
);