PlugWiki

How to Build a Custom MCP Server

A custom MCP server gives Claude tools you define. Pick an official SDK, write a tool, test it in MCP Inspector, then add it to Claude.

A custom MCP server is a small program that gives Claude tools you define, such as a function, a database query or your company's API. You write it with an official SDK in the language you already use, test it in MCP Inspector, then add it to Claude Code or Claude Desktop. Step-by-step guides for Python, TypeScript, Rust and Java are linked below.

Our advice: if you have no language preference, start with TypeScript or Python. Both are Tier 1 SDKs and have the shortest path from nothing to a working tool.

The one rule that catches most people: a local server talks to Claude over stdout, so never print anything to stdout in it. Log to stderr instead.

The MCP project lists official SDKs for ten languages. Six are Tier 1 (TypeScript, Python, C#, Go, Rust, Ruby), Java is Tier 2, and Swift, PHP and Kotlin are Tier 3. The tiers rate feature completeness, protocol support and maintenance commitment.

Good for

  • Developers who want Claude to call their own functions, databases or APIs
  • Teams wrapping an internal service so Claude can use it
  • Anyone choosing a language or framework before they start

Build, test and connect a custom MCP server

  1. 1

    Decide what the server does

    Start with one job. Each tool is a function with a name, a description and an input schema, and Claude reads the description to decide when to call it.

    Our advice: build one tool first, then add more once it works in Claude.

  2. 2

    Pick a language

    Use the language your team already ships. All official SDKs let you build servers with tools, resources and prompts.

    • Python: package mcp, Python 3.11 or later, Tier 1.
    • TypeScript: package @modelcontextprotocol/server, Tier 1.
    • Rust: crate rmcp, Rust 1.88 or later, Tier 1.
    • Java: Maven artifact mcp, Java 17 or later, Tier 2.

    C#, Go and Ruby are also Tier 1. Swift, PHP and Kotlin are Tier 3.

  3. 3

    Choose local or remote

    A local server runs on your machine over stdio. Claude Code and Claude Desktop launch it as a child process, which is the standard way to run a local MCP server. It is the simplest start and needs no hosting.

    A remote server is served by URL over Streamable HTTP, so several people can connect to one running copy. Build local first, then switch the transport when you need to share it.

  4. 4

    Write one tool in your SDK

    Follow the guide for your language. The shape is the same in all of them: create a server object, register a function as a tool, and call the run or serve method with the stdio transport.

    The SDKs build the input schema from your types (Python type hints, a Zod schema in TypeScript, a Rust struct).

    Tip: On stdio, print nothing to stdout. In Python that means no print(), in TypeScript no console.log().

  5. 5

    Test it in MCP Inspector

    Run npx @modelcontextprotocol/inspector followed by the command that starts your server, then open the URL it prints. Go to Tools, pick your tool, enter test arguments and run it. Fix the result here before you involve Claude.

    The Inspector needs Node 22.19 or later. See MCP Inspector for its CLI and terminal modes.

  6. 6

    Add it to Claude Code

    Run claude mcp add <name> -- <launch command> with the same command the Inspector used and absolute paths. Then run /mcp in a Claude Code session to confirm it is connected.

    Add --scope project to store it in .mcp.json at the project root so your team gets it.

    Prompt
    Use my server to run its main tool with a test input.
  7. 7

    Or add it to Claude Desktop

    Add an entry under mcpServers in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json).

    Fully quit Claude Desktop and reopen it. Closing the window does not reload the config.

Code

terminal
# 1. Test in MCP Inspector (put your own launch command after the package name)
npx @modelcontextprotocol/inspector <launch command>

# 2. Add to Claude Code (everything after -- is the launch command)
claude mcp add my-server -- <launch command>

# 3. Check it inside a Claude Code session
/mcp
Examples of a launch command: uv run mcp run /absolute/path/server.py (Python), node /absolute/path/build/index.js (TypeScript), /absolute/path/target/release/my-server (Rust), java -jar /absolute/path/server.jar (Java).
claude_desktop_config.json
{
  "mcpServers": {
    "my-server": {
      "command": "<program, for example node or java>",
      "args": ["<absolute path or arguments>"]
    }
  }
}
The same command and arguments you used with the Inspector. Fully quit and reopen Claude Desktop after saving.

Common errors and fixes

  • Server connects, then drops, or shows as failed in Claude

    Cause: Something wrote to stdout, such as print() in Python or console.log() in TypeScript. On a stdio server, stdout carries the protocol.

    Fix: Remove it. Log to stderr or a file instead.

    claude-desktop, claude-code Source

  • Server does not appear in Claude Desktop after editing claude_desktop_config.json

    Cause: A relative path, a JSON syntax error, or Claude Desktop is still running with the old config.

    Fix: Use absolute paths, check the JSON, then fully quit and reopen Claude Desktop.

    claude-desktop Source

  • The host cannot start the server because a command such as uv is not found

    Cause: Hosts launch servers with a minimal PATH that may not include your tools.

    Fix: Put the full path of the command in "command", from `which <command>` on macOS or Linux or `where <command>` on Windows.

    claude-desktop, cursor, vs-code Source

Questions

What is a custom MCP server?

A program you write that exposes your own tools to Claude or another AI assistant. A tool is a function with a name, a description and an input schema. The assistant decides when to call it and shows you the result.

How do I build an MCP server?

Pick an official SDK, register a function as a tool, test it in MCP Inspector, then add it to Claude Code or Claude Desktop. The Python, TypeScript, Rust and Java guides each cover the steps with code.

Which language should I use for an MCP server?

Use the language your team already works in. There are official SDKs for TypeScript, Python, C#, Go, Rust, Ruby, Java, Swift, PHP and Kotlin. Our advice: pick TypeScript or Python if you have no preference, since both are Tier 1.

Do I need to host an MCP server?

No, not for your own use. A local server runs on your machine and Claude Code or Claude Desktop launches it over stdio. You only need hosting when other people should connect to one running copy by URL.

What is FastMCP, and should I use it or the official SDK?

FastMCP is the name of a Python framework (fastmcp on PyPI) and of a TypeScript one (fastmcp on npm), both separate from the official SDKs. The official Python SDK also had a FastMCP class in v1, renamed MCPServer in v2. Our advice: start with the official SDK, and move to a framework if you want its extra features.

How do I test an MCP server?

Run npx @modelcontextprotocol/inspector followed by your server's launch command. The Inspector lists the tools, runs them with your arguments and shows the result. It needs Node 22.19 or later.

How do I add my MCP server to Claude Code?

Run claude mcp add <name> -- <launch command> with absolute paths, then /mcp in a session to confirm it is connected. The command is in the Code section above.

How do I add it to Claude Desktop?

Add an entry under mcpServers in claude_desktop_config.json, then fully quit and reopen Claude Desktop. The entry uses the same command and arguments you used with the Inspector.

Why does my server break when I print to the console?

A local server uses stdout to talk to the host, so anything you print there corrupts the messages. Use stderr or a log file instead, such as Python's logging module or console.error() in TypeScript.

Sources

Docs, issue trackers and discussions this page is built from.

Show all 12
  1. SDKs - Model Context Protocol · modelcontextprotocol.io
  2. Build an MCP server · modelcontextprotocol.io
  3. rmcp README: Transports · github.com
  4. Installation (Python SDK) · py.sdk.modelcontextprotocol.io
  5. rust-sdk workspace Cargo.toml · github.com
  6. MCP Java SDK README · github.com
  7. MCP Inspector · modelcontextprotocol.io
  8. Connect to a real host (Python SDK docs) · py.sdk.modelcontextprotocol.io
  9. Connect Claude Code to tools via MCP · code.claude.com
  10. fastmcp on PyPI · pypi.org
  11. fastmcp on npm · npmjs.com
  12. What's new in v2 (Python SDK) · py.sdk.modelcontextprotocol.io

Updated Nov 3, 2026.