When to Build Your Own Server

Community servers cover most common integrations. You build your own when:

You need to connect Claude to an internal API that no public server supports
You want to expose domain-specific logic (your company's deployment scripts, your data pipeline)
You need custom security controls that off-the-shelf servers don't provide
You want to compose multiple APIs into a single, coherent interface for the AI

The good news: building an MCP server is straightforward. The SDK handles all the protocol complexity. You just define your tools and their logic.

Part 1: TypeScript MCP Server

We'll build a weather server that exposes two tools: get_forecast and get_alerts. Claude will be able to check weather conditions and severe weather alerts for any US location.

Project Setup

Create a new directory and initialize the project:

The Server Code

Here's the complete server. Every line is explained:

Key Concepts in the Code

Tool Registration: Each tool is registered with server.tool(name, schema, handler). The schema uses Zod for validation — the SDK auto-generates the JSON Schema that Claude sees.

Input Validation: Zod validates inputs before your handler runs. If Claude passes invalid arguments, the SDK returns a clear error.

Error Handling: Return isError: true with a descriptive message. Never throw unhandled exceptions — they crash the server and disconnect from Claude.

Stdio Transport: The server communicates through stdin/stdout. Never use console.log() in an MCP server — it writes to stdout and corrupts the protocol. Use console.error() for debugging (writes to stderr).

Part 2: Python MCP Server

The Python SDK uses FastMCP, which is more concise thanks to decorators and type annotations. Here's the same weather server in Python:

Python Setup

Python MCP servers require Python 3.10+ and the mcp package:

Key Differences from TypeScript

Decorators vs explicit registration: Python uses @mcp.tool() decorators. TypeScript uses server.tool() calls.

Type inference: Python auto-generates schemas from type annotations and docstrings. TypeScript requires explicit Zod schemas with .describe().

Less boilerplate: The Python version is about 40% shorter for equivalent functionality.

Connecting Your Server to Claude

Add your server to Claude Desktop's config:

For the TypeScript version, first build it (npm run build), then point the config at the built file. For the Python version, use uv run to execute directly.

Testing Your Server

Before connecting to Claude, test your server independently:

For TypeScript, the MCP Inspector tool is invaluable:

This launches a web UI where you can call each tool, inspect inputs/outputs, and debug issues — without needing Claude in the loop.

Adding Resources and Prompts

Tools are just one primitive. You can also add resources (static data Claude can read) and prompts (templates for common tasks):

What's Next

You now have a working MCP server. In Lesson 5, we'll secure it — because right now, anyone who can reach your server can call any tool with any arguments. That's fine for local development, but dangerous in production.

For more MCP server examples and starter templates, browse our repository directory.

Building a Custom MCP Server from Scratch

Related Resources