Build Your Own MCP Server — Step-by-Step Guide

What it is

This is a comprehensive guide to building a custom Model Context Protocol (MCP) server from scratch. It covers the MCP protocol fundamentals, TypeScript and Python SDK usage, tool definition patterns, resource management, testing strategies, and deployment options. MCP servers extend AI agents like Claude Code with custom capabilities -- database access, API integrations, file processing, and more.

The guide targets developers who want to give their AI coding agents access to specific tools and data sources not covered by existing MCP servers. Building a custom server lets you expose your organization's internal APIs, databases, or services to AI agents securely.

How it saves time or tokens

A custom MCP server lets AI agents interact with your systems directly instead of relying on you to copy-paste data between tools. The agent calls your server's tools, gets results, and incorporates them into its workflow. This eliminates the manual intermediary role and reduces the tokens spent on describing data that the agent could query directly.

How to use

1. Scaffold a new MCP server (TypeScript recommended):

npx @anthropic/create-mcp-server my-mcp-server
cd my-mcp-server && npm run dev

1. Or use Python:

pip install mcp

1. Define tools and add to your .mcp.json to test with Claude Code.

Example

A minimal MCP server with a custom tool in TypeScript:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

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

server.tool(
  'lookup_user',
  'Find a user by email address',
  { email: z.string().email() },
  async ({ email }) => {
    const user = await db.findUserByEmail(email);
    return { content: [{ type: 'text', text: JSON.stringify(user) }] };
  }
);

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

This server exposes a lookup_user tool that Claude Code can call during conversations.

Related on TokRepo

• MCP Chrome Integration — Example MCP server for browser automation
• MCP PostgreSQL Integration — Example MCP server for database access

Common pitfalls

• MCP servers communicate via stdio. Logging to stdout breaks the protocol. Use stderr for debug output.
• Tool descriptions are sent to the LLM as context. Vague descriptions lead to incorrect tool usage. Write clear, specific descriptions for each tool.
• Input validation is critical. The LLM may send unexpected parameter values. Use Zod schemas (TypeScript) or Pydantic models (Python) to validate all inputs.