How to Build an MCP Server: Complete Developer Guide (2026)

To build an MCP server, choose an SDK (Python, TypeScript, Go, Kotlin, or Rust), define tools as functions the AI model can call, test with the MCP Inspector, and connect to a client like Claude Desktop. The official SDKs handle all protocol complexity -- JSON-RPC messaging, capability negotiation, transport management -- so you focus entirely on the logic your tools perform. A basic MCP server with two or three tools can be built and running in under 30 minutes.

This guide is the language-agnostic starting point for building any MCP server. It covers the decisions you need to make, the patterns that work across all languages, and the workflow from idea to production deployment. For language-specific step-by-step tutorials, follow the links to our Python MCP server guide and TypeScript and Go MCP server guide.

What Is an MCP Server?

An MCP server is a program that exposes capabilities -- tools, resources, and prompts -- to AI models through the Model Context Protocol. Think of it as a bridge between an AI assistant and the external systems you want it to interact with: APIs, databases, file systems, cloud services, and more.

The key insight behind MCP is standardization. Before MCP, every AI integration was custom. Each tool, each API, each data source required bespoke code to connect to each AI client. MCP replaces that with a single, open protocol that works with any compatible client.

For a deeper understanding of MCP concepts, see What Is an MCP Server? and MCP Core Building Blocks.

How MCP Servers Work

┌──────────────────┐         JSON-RPC          ┌──────────────────┐
│                  │  ◄─────────────────────►   │                  │
│   MCP Client     │    (stdio, SSE, or         │   MCP Server     │
│   (Claude, etc.) │     Streamable HTTP)       │   (your code)    │
│                  │                            │                  │
└──────────────────┘                            └──────┬───────────┘
                                                       │
                                                       ▼
                                                ┌──────────────────┐
                                                │  External System │
                                                │  (API, DB, etc.) │
                                                └──────────────────┘

1. The client (Claude Desktop, Cursor, an AI agent) connects to your server
2. Your server declares its capabilities (tools, resources, prompts)
3. The AI model decides when to call your tools based on the user's request
4. Your server executes the tool logic and returns results
5. The AI model uses the results to formulate its response

Step 1: Decide What Your Server Will Do

Before writing code, answer these questions:

What external system or data source are you connecting? The best MCP servers focus on a single integration point: a specific API, a database, a file system, a SaaS tool. Avoid building a "do everything" server.

What actions should the AI be able to take? These become your tools. List them out:

What context should the AI have access to? These become your resources:

Are there reusable workflows? These become your prompts:

Most servers start with tools only. Add resources and prompts later as you identify needs. For detailed guidance on designing tools, see Creating Custom Tools and Resources.

Step 2: Choose Your Language and SDK

The MCP ecosystem offers official and community SDKs for several languages. Your choice depends on your team's expertise, the libraries you need, and your deployment constraints.

SDK Comparison Table

When to Choose Each

Choose Python if:

• You want the fastest path from idea to working server
• You need data science or ML libraries (pandas, scikit-learn, PyTorch)
• You prefer a concise, decorator-based API
• You are building a prototype or internal tool

Choose TypeScript if:

• Your team lives in the Node.js ecosystem
• You want the most community examples (the majority of open-source MCP servers use TypeScript)
• You need tight integration with JavaScript-based tools and frameworks
• You want explicit control over JSON schemas and handlers

Choose Go if:

• You need minimal memory footprint and fast cold starts
• You are deploying to containerized environments where resource efficiency matters
• You prefer compiled binaries with no runtime dependencies
• You are building high-throughput production servers

Choose Kotlin if:

• Your team works in the JVM ecosystem
• You want to integrate with existing Java/Spring services
• You need access to JVM libraries and tooling

Choose Rust if:

• Maximum performance and memory safety are non-negotiable
• You are building infrastructure-level servers
• Your team is already proficient in Rust

For detailed tutorials, see:

• How to Build Your First MCP Server in Python
• Building MCP Servers in TypeScript and Go

Step 3: Set Up Your Project

Each SDK has its own project initialization flow. Here is a quick-start for the three most popular options.

Python (FastMCP)

# Create project directory
mkdir my-mcp-server && cd my-mcp-server

# Initialize with uv (recommended package manager)
uv init
uv add "mcp[cli]"

# Create your server file
touch server.py

TypeScript

# Create project directory
mkdir my-mcp-server && cd my-mcp-server

# Initialize Node.js project
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript tsx @types/node

# Initialize TypeScript config
npx tsc --init

# Create source directory
mkdir src && touch src/index.ts

Go

# Create project directory
mkdir my-mcp-server && cd my-mcp-server

# Initialize Go module
go mod init github.com/yourname/my-mcp-server
go get github.com/modelcontextprotocol/go-sdk/mcp
go get github.com/modelcontextprotocol/go-sdk/server

# Create main file
touch main.go

Step 4: Define Your Tools

Tools are the core of most MCP servers. A well-designed tool has a clear name, a helpful description, typed parameters, and returns useful text output.

Tool Design Principles

1. One tool, one action. Each tool should do exactly one thing. Instead of a manage_issues tool with a mode parameter, create search_issues, create_issue, and close_issue.

2. Descriptive names and descriptions. The AI model reads your tool name and description to decide when to use it. Be specific: search_github_issues is better than search.

3. Typed parameters with documentation. Define every parameter with a type, description, and whether it is required or optional. The richer your schema, the better the AI uses your tool.

4. Return useful text. The AI model reads your tool's return value as text. Format results clearly -- use structured text, tables, or lists rather than raw JSON when possible.

5. Handle errors gracefully. Return a descriptive error message rather than crashing. The AI model can use error information to retry or adjust its approach.

Tool Implementation Patterns

Here is the same tool implemented in Python, TypeScript, and Go to show how the SDKs differ:

Python (FastMCP):

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("GitHub Server")

@mcp.tool()
async def search_issues(
    query: str,
    state: str = "open",
    max_results: int = 10,
) -> str:
    """Search GitHub issues in the configured repository.

    Args:
        query: Search terms to match against issue titles and bodies
        state: Filter by issue state - 'open', 'closed', or 'all'
        max_results: Maximum number of results to return (1-100)
    """
    issues = await github_client.search_issues(
        query=query, state=state, per_page=max_results
    )

    if not issues:
        return f"No issues found matching '{query}' with state '{state}'."

    lines = [f"Found {len(issues)} issues:\n"]
    for issue in issues:
        lines.append(
            f"- #{issue['number']} [{issue['state']}] {issue['title']}"
        )
    return "\n".join(lines)

TypeScript:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "search_issues",
      description:
        "Search GitHub issues in the configured repository",
      inputSchema: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "Search terms to match against issue titles and bodies",
          },
          state: {
            type: "string",
            enum: ["open", "closed", "all"],
            description: "Filter by issue state",
            default: "open",
          },
          max_results: {
            type: "number",
            description: "Maximum number of results (1-100)",
            default: 10,
          },
        },
        required: ["query"],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "search_issues") {
    const { query, state = "open", max_results = 10 } =
      request.params.arguments as {
        query: string;
        state?: string;
        max_results?: number;
      };

    const issues = await githubClient.searchIssues(query, state, max_results);

    if (issues.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No issues found matching '${query}' with state '${state}'.`,
          },
        ],
      };
    }

    const text = issues
      .map((i) => `- #${i.number} [${i.state}] ${i.title}`)
      .join("\n");

    return {
      content: [{ type: "text", text: `Found ${issues.length} issues:\n\n${text}` }],
    };
  }

  throw new Error(`Unknown tool: ${request.params.name}`);
});

Go:

package main

import (
    "context"
    "fmt"
    "strings"

    "github.com/modelcontextprotocol/go-sdk/mcp"
    "github.com/modelcontextprotocol/go-sdk/server"
)

func main() {
    s := server.NewMCPServer(
        "github-server",
        "1.0.0",
        server.WithToolCapabilities(true),
    )

    s.AddTool(
        mcp.Tool{
            Name:        "search_issues",
            Description: ptrTo("Search GitHub issues in the configured repository"),
            InputSchema: mcp.ToolInputSchema{
                Type: "object",
                Properties: map[string]interface{}{
                    "query": map[string]interface{}{
                        "type":        "string",
                        "description": "Search terms to match against issue titles and bodies",
                    },
                    "state": map[string]interface{}{
                        "type":        "string",
                        "enum":        []string{"open", "closed", "all"},
                        "description": "Filter by issue state",
                        "default":     "open",
                    },
                },
                Required: []string{"query"},
            },
        },
        func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
            query := req.Params.Arguments["query"].(string)
            state := "open"
            if s, ok := req.Params.Arguments["state"].(string); ok {
                state = s
            }

            issues, err := searchGitHubIssues(ctx, query, state)
            if err != nil {
                return nil, fmt.Errorf("search failed: %w", err)
            }

            if len(issues) == 0 {
                return mcp.NewToolResultText(
                    fmt.Sprintf("No issues found matching '%s'.", query),
                ), nil
            }

            var lines []string
            for _, issue := range issues {
                lines = append(lines,
                    fmt.Sprintf("- #%d [%s] %s", issue.Number, issue.State, issue.Title),
                )
            }

            return mcp.NewToolResultText(
                fmt.Sprintf("Found %d issues:\n\n%s", len(issues), strings.Join(lines, "\n")),
            ), nil
        },
    )

    // Start with stdio transport
    if err := server.ServeStdio(s); err != nil {
        panic(err)
    }
}

Notice how all three implementations produce the same MCP protocol messages despite very different API styles. This is the power of standardization.

Step 5: Add Resources and Prompts

Resources and prompts are optional but powerful additions to your server.

Resources: Providing Context

Resources give the AI model background information without requiring a tool call. Common resource patterns:

@mcp.resource("schema://database/tables")
async def get_database_schema() -> str:
    """Provide the database schema for context."""
    tables = await db.get_table_definitions()
    return format_schema(tables)

@mcp.resource("config://app/settings")
async def get_app_config() -> str:
    """Provide current application configuration."""
    config = load_config()
    return format_config(config)

Dynamic Resource Templates

For resources that depend on parameters, use URI templates:

@mcp.resource("repo://{owner}/{name}/readme")
async def get_repo_readme(owner: str, name: str) -> str:
    """Get the README for a specific repository."""
    return await github_client.get_readme(owner, name)

Prompts: Reusable Workflows

Prompts encode expert workflows that users can invoke:

@mcp.prompt()
def code_review(diff: str) -> str:
    """Review a code diff for bugs, style issues, and improvements."""
    return f"""Please review the following code diff. Focus on:
1. Potential bugs or logic errors
2. Security concerns
3. Performance implications
4. Code style and readability
5. Test coverage gaps

Diff to review:

{diff}"""

For comprehensive coverage of tool and resource design, see Creating Custom Tools and Resources and MCP Core Building Blocks.

Step 6: Test with MCP Inspector

The MCP Inspector is your primary development tool. It connects to your server and provides an interactive UI for testing every capability.

Launching the Inspector

Python:

mcp dev server.py

TypeScript:

npx @modelcontextprotocol/inspector node dist/index.js

Go (or any compiled server):

npx @modelcontextprotocol/inspector ./my-mcp-server

The Inspector opens at http://localhost:5173 and provides panels for testing tools, browsing resources, viewing prompts, and inspecting raw JSON-RPC messages.

What to Test

For a complete guide to testing and debugging, see Testing and Debugging MCP Servers.

Step 7: Connect to a Client

Once your server passes Inspector testing, connect it to a real AI client.

Claude Desktop

Add your server to the Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/my-mcp-server", "run", "server.py"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

For TypeScript servers:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/dist/index.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop after editing the config. Your server's tools should appear in the tools menu (the hammer icon).

For detailed client setup guides, see Connecting MCP Servers to Claude Desktop and MCP in Cursor and VS Code.

Other Clients

MCP is an open standard. Your server works with any compliant client:

Step 8: Write Automated Tests

Manual testing with the Inspector is essential during development, but automated tests catch regressions and validate edge cases over time.

Unit Tests: Test Tool Logic

Extract your business logic into testable functions:

# test_tools.py
import pytest
from tools import format_issues, validate_query

def test_format_issues_empty():
    result = format_issues([])
    assert "No issues found" in result

def test_format_issues_multiple():
    issues = [
        {"number": 1, "state": "open", "title": "Bug report"},
        {"number": 2, "state": "closed", "title": "Feature request"},
    ]
    result = format_issues(issues)
    assert "#1" in result
    assert "#2" in result
    assert "Bug report" in result

def test_validate_query_rejects_empty():
    with pytest.raises(ValueError):
        validate_query("")

Integration Tests: Test the MCP Protocol

Use the SDK's in-memory transport to test the complete protocol flow:

import pytest
import asyncio
from mcp import ClientSession
from mcp.client.session import InMemoryTransport
from server import mcp as my_server

@pytest.mark.asyncio
async def test_tools_are_listed():
    async with InMemoryTransport() as (client_t, server_t):
        server_task = asyncio.create_task(
            my_server._mcp_server.run(
                server_t[0], server_t[1],
                my_server._mcp_server.create_initialization_options(),
            )
        )
        async with ClientSession(client_t[0], client_t[1]) as session:
            await session.initialize()
            tools = await session.list_tools()
            tool_names = [t.name for t in tools.tools]
            assert "search_issues" in tool_names
            assert "create_issue" in tool_names
        server_task.cancel()

For comprehensive testing strategies, see Testing and Debugging MCP Servers.

Step 9: Architecture Decisions

Before deploying, make key architecture decisions that affect how your server operates.

Local vs Remote Deployment

Most servers start as local stdio servers during development, then migrate to remote deployment for production. For the full comparison, see Local vs Remote MCP Servers.

Stateless vs Stateful

Stateless servers (recommended default):

• Each tool call is independent
• No in-memory state between calls
• Horizontally scalable without coordination
• External state lives in a database or API

Stateful servers (when needed):

• Maintain session context (e.g., conversation memory, undo history)
• Require sticky sessions for remote deployments
• Use Redis or a database for shared state across instances
• More complex to scale and debug

Transport Selection

For new remote servers, prefer Streamable HTTP unless you specifically need server-initiated push notifications.

Step 10: Deploy and Distribute

Deployment Options

For detailed deployment instructions, see Deploying Remote MCP Servers.

Publishing Your Server

Python (PyPI):

uv build
uv publish

Users install with: uv add your-mcp-server or pip install your-mcp-server

TypeScript (npm):

Add a bin field to package.json:

{
  "name": "your-mcp-server",
  "bin": {
    "your-mcp-server": "./dist/index.js"
  }
}

npm publish

Users run with: npx your-mcp-server

Docker:

docker build -t your-mcp-server .
docker push your-dockerhub-user/your-mcp-server

Listing in the MCP Server Directory

Make your server discoverable by listing it in the MCP Server Directory. Include a clear description of what your server does, which tools it exposes, and how to install it.

The Complete Development Workflow

Here is the end-to-end workflow summarized:

1. Define scope       What system? What tools? What data?
        │
        ▼
2. Choose SDK         Python / TypeScript / Go / Kotlin / Rust
        │
        ▼
3. Set up project     Initialize, install SDK, create structure
        │
        ▼
4. Implement tools    Write tool functions with types and docs
        │
        ▼
5. Test interactively Use MCP Inspector to verify every tool
        │
        ▼
6. Connect client     Configure Claude Desktop or Cursor
        │
        ▼
7. Automate tests     Unit tests + integration tests with in-memory transport
        │
        ▼
8. Add observability  Logging, metrics, health checks
        │
        ▼
9. Deploy             Docker, cloud platform, or local distribution
        │
        ▼
10. Publish           PyPI, npm, Docker Hub + MCP Server Directory

Common Pitfalls and How to Avoid Them

What to Read Next

• Python tutorial: How to Build Your First MCP Server in Python -- step-by-step from zero to a working weather server
• TypeScript and Go tutorial: Building MCP Servers in TypeScript and Go -- complete guides for both languages
• Tool design: Creating Custom Tools and Resources -- advanced tool patterns and best practices
• Testing: Testing and Debugging MCP Servers -- Inspector, unit tests, and integration tests
• Deployment: Deploying Remote MCP Servers -- Docker, cloud hosting, and scaling
• Monitoring: MCP Server Monitoring and Observability -- Prometheus, Grafana, and alerting
• Fundamentals: What Is an MCP Server? and MCP Building Blocks
• Browse servers: MCP Server Directory -- see what others have built for inspiration

Summary

Building an MCP server follows a straightforward path: decide what capabilities to expose, choose an SDK that fits your team, implement tools as regular functions, test with the Inspector, and deploy to your target environment. The official SDKs eliminate all protocol complexity, letting you focus on the logic that matters -- connecting AI models to the systems and data they need.

Start with a small, focused server (two or three tools wrapping an API you already know). Get it working end-to-end with Claude Desktop. Then iterate: add more tools, improve error handling, write tests, and deploy to production. The ecosystem is growing rapidly, and the patterns established in this guide will serve you well regardless of which language or platform you choose.