How to Build Your Own MCP Server (TypeScript Tutorial)

If the existing MCP servers don't cover your use case, you can build your own. MCP servers are relatively simple programs — they expose tools through a standardized protocol, and any compatible agent can use them. This tutorial walks through building one in TypeScript.

What you're building

An MCP server is a program that:

1. Connects to an AI agent via a transport (stdio for local, HTTP for remote)
2. Responds to a tools/list request with the tools it provides
3. Handles tools/call requests by executing the requested tool and returning results

That's the core loop. Everything else is your tool logic.

Project setup

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

Basic server structure

Create src/index.ts:

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

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

// Define your tools
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_weather",
      description: "Get current weather for a city",
      inputSchema: {
        type: "object",
        properties: {
          city: { type: "string", description: "City name" }
        },
        required: ["city"]
      }
    }
  ]
}));

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "get_weather") {
    const city = request.params.arguments?.city;
    // Your actual logic here
    return {
      content: [{ type: "text", text: `Weather in ${city}: 22°C, sunny` }]
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

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

Testing with Claude Code

Build your server and add it to Claude Code's config:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/dist/index.js"]
    }
  }
}

Restart Claude Code and ask it something that should trigger your tool. If it's working, you'll see the agent discover and use your tool automatically.

Adding real functionality

The example above returns hardcoded data. A real server would connect to APIs, databases, or local services. The pattern is always the same: define the tool's schema, handle the call, return results.

Common patterns for real MCP servers:

API wrapper. Call an external REST API and return formatted results. Handle authentication, rate limiting, and error cases.

Database query. Connect to a database, execute queries, and return results. Be careful with permissions — expose read-only access unless writes are explicitly needed.

File processor. Read files, transform them, and return results. Useful for format conversion, analysis, or content extraction.

Publishing and distribution

Once your server works, you can publish it as an npm package for others to use. If you want it discoverable by the AI agent community, list it on the Agensi MCP directory where it will be security-scanned and made available to all MCP-compatible agents.