Build a Custom MCP Server for Claude Code: The Complete Guide

Unlocking seamless integration between AI assistants and your internal systems is the next leap in developer productivity. The Model Context Protocol (MCP) makes this possible by providing a standardized, discoverable way for tools like Claude Code to interact with any API, database, or custom service—without hardcoded integrations.

If you're an API developer, backend engineer, or technical lead looking to supercharge your team's workflows, this guide delivers a clear, actionable roadmap to building your own MCP server. You’ll learn to architect, implement, and secure a server that extends Claude Code’s capabilities far beyond its defaults—empowering your team to automate, query, and orchestrate with unprecedented flexibility.

💡 Looking for an API testing platform that generates beautiful API documentation and enables high-productivity, all-in-one teamwork? Apidog replaces Postman at a far more affordable price and delivers everything your developer team needs.

button

What Is MCP and Why Should Developers Care?

The Value of MCP for API Teams

MCP (Model Context Protocol)—created by Anthropic—enables AI assistants like Claude Code to securely and dynamically discover, understand, and use external tools over a unified protocol. Unlike static API integrations, MCP lets you add new tools and endpoints without updating the AI client, making extensibility effortless.

Key benefits for engineering teams:

Discoverability: Expose new tools or APIs instantly—no client update required.
Type Safety: All tool schemas are validated before execution, reducing runtime errors.
Dynamic Tooling: Connect to databases, microservices, file systems, or any RESTful API.

How MCP Works: Architecture Overview

MCP Host: The AI assistant (e.g., Claude Code) that consumes tool capabilities.
MCP Server: Your custom program exposing capabilities via the MCP protocol.
MCP Client: Handles 1:1 communication between host and server.
Transport Layer: Local servers use stdio (stdin/stdout); remote servers can use SSE.

Typical MCP Workflow

Discovery: Claude Code queries your server for available tools.
Schema Validation: The server returns schemas and definitions.
Tool Selection: Claude Code matches user intent to available tools.
Execution: Tool calls are sent with validated parameters.
Response: The server processes the request and returns structured results.

Apidog will soon support MCP servers—allowing you to feed API docs directly into your AI workflows for instant, always-up-to-date reference.

We’re thrilled to share that MCP support is coming soon to Apidog! 🚀 Apidog MCP Server lets you feed API docs directly to Agentic AI, supercharging your vibe coding experience! Whether you're using Cursor, Cline, or Windsurf - it'll make your dev process faster and smoother.… pic.twitter.com/ew8U38mU0K
— Apidog (@ApidogHQ) March 19, 2025

Prerequisites: Setting Up Your Environment

Before building, ensure your development environment is ready. MCP servers are most commonly built in Python or TypeScript.

For Python:

Python 3.8+ (async/await, type annotations)
pip for dependencies
Virtual environment tools (venv or conda)

For TypeScript/JavaScript:

Node.js v20+
npm or yarn
TypeScript compiler

Core Tools:

Claude Code CLI: Manage and test MCP servers.
Basic JSON-RPC 2.0 understanding.
Familiarity with server request/response patterns.

Environment Setup Steps

1. Install Claude Code CLI Globally

npm install -g @anthropic-ai/claude-code

Global install ensures claude is accessible system-wide and prevents path issues.

2. Verify Installation

claude --version
claude --help

3. Initial Permissions Setup (Critical!)

claude --dangerously-skip-permissions

Initializes config directories and MCP registry.
Sets up permissions for secure communication.
Note: This flag is safe for development. In production, review each prompt carefully.

MCP Server Configuration: Understanding Scopes

Why Scopes Matter

Misconfigured scopes are the #1 cause of “server not found” errors. Scopes control where and when Claude Code can see your server:

Scope Hierarchy

Project Scope (.mcp.json):
- Highest priority; config in project root.
- Use for project-specific tools (e.g., local DB, linters).
User Scope (--scope user):
- Global across all projects.
- Ideal for general utilities and shared tools.
Local Scope (default):
- Only accessible in the registration directory.
- For quick, temporary setups.

Example: Avoiding Common Mistakes

Wrong (local only):

claude mcp add my-server python3 /path/to/server.py

Right (global user scope):

claude mcp add --scope user my-server python3 /path/to/server.py

Organize for Maintainability

Structure your MCP servers for easy management:

mkdir -p ~/.claude-mcp-servers/apis/
mkdir -p ~/.claude-mcp-servers/utilities/
mkdir -p ~/.claude-mcp-servers/development/

Benefits: Easier updates, security, backup, and team sharing.

Troubleshooting Scope Issues

Run claude mcp list to check visible servers.
Look for a local .mcp.json that might override your config.
Test from different directories to isolate scope issues.

Step-by-Step: Build Your First MCP Server

1. Project Foundation

Create an isolated project directory:

cd ~/.claude-mcp-servers/
mkdir my-first-server
cd my-first-server
touch server.py requirements.txt .env

2. MCP Server Basics (Python Example)

Below is a minimal MCP server that implements the essential methods:

#!/usr/bin/env python3
import json, sys, os

# Unbuffered output for real-time communication
sys.stdout = os.fdopen(sys.stdout.fileno(), 'w', 1)

def send_response(resp): print(json.dumps(resp), flush=True)

def handle_initialize(req_id):
    return {"jsonrpc": "2.0", "id": req_id, "result": {
        "protocolVersion": "2024-11-05",
        "capabilities": {"tools": {}},
        "serverInfo": {"name": "my-custom-server", "version": "1.0.0"}
    }}

def handle_tools_list(req_id):
    return {"jsonrpc": "2.0", "id": req_id, "result": {"tools": [{
        "name": "hello_world",
        "description": "A simple demonstration tool",
        "inputSchema": {"type": "object", "properties": {"name": {
            "type": "string", "description": "Name to greet"}}, "required": ["name"]}
    }]}}

def handle_tool_call(req_id, params):
    tool, args = params.get("name"), params.get("arguments", {})
    if tool == "hello_world":
        name = args.get("name", "World")
        result = f"Hello, {name}! Your MCP server is working perfectly."
    else:
        return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": f"Unknown tool: {tool}"}}
    return {"jsonrpc": "2.0", "id": req_id, "result": {"content": [{"type": "text", "text": result}]}}

def main():
    while True:
        try:
            line = sys.stdin.readline()
            if not line: break
            req = json.loads(line.strip())
            m, req_id, params = req.get("method"), req.get("id"), req.get("params", {})
            if m == "initialize": resp = handle_initialize(req_id)
            elif m == "tools/list": resp = handle_tools_list(req_id)
            elif m == "tools/call": resp = handle_tool_call(req_id, params)
            else: resp = {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": f"Method not found: {m}"}}
            send_response(resp)
        except Exception: continue

if __name__ == "__main__": main()

Key Points:

Unbuffered I/O for real-time protocol compliance.
Handles initialize, tools/list, and tools/call MCP methods.

3. Make the Server Executable

chmod +x server.py

4. Test Protocol Compliance

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 server.py

You should see a valid JSON response with protocol version and capabilities.

5. Register with Claude Code

claude mcp add --scope user my-first-server python3 ~/.claude-mcp-servers/my-first-server/server.py
claude mcp list
claude mcp get my-first-server

Real-World Example: Integrate a Weather API

Let’s evolve your MCP server into a production-useful tool by connecting to the OpenWeatherMap API.

Server highlights:

Secure API key handling via environment variables
Real API calls, error-handling, and input validation

Sample Implementation

import json, sys, os, requests

WEATHER_API_KEY = os.environ.get("OPENWEATHER_API_KEY", "your-api-key-here")

def get_weather(city):
    url = "http://api.openweathermap.org/data/2.5/weather"
    params = {"q": city, "appid": WEATHER_API_KEY, "units": "metric"}
    try:
        r = requests.get(url, params=params, timeout=10)
        data = r.json()
        if r.status_code == 200:
            return f"Weather in {city}: {data['main']['temp']}°C, {data['weather'][0]['description'].title()}, Humidity: {data['main']['humidity']}%"
        return f"Error fetching weather: {data.get('message', 'Unknown error')}"
    except requests.RequestException as e:
        return f"Network error: {str(e)}"

Tool schema and error handling are updated to match production needs.

Security: Store your API key in .env and never commit secrets to version control.

Testing and Debugging Your MCP Server

Manual Testing

Test initialize, tools/list, and tools/call by piping JSON into your script and inspecting responses.

Run:

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"London"}}}' | python3 server.py

Automated Test Example

import json, subprocess, sys
def test_mcp_method(method, params=None):
    req = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}
    result = subprocess.run([sys.executable, "server.py"], input=json.dumps(req), capture_output=True, text=True, timeout=10)
    return json.loads(result.stdout.strip())

Integration Testing

Register your server and invoke it directly from Claude Code.
Check the naming convention: mcp__<server-name>__<tool-name>

Best Practices for Production MCP Servers

Security

Never hardcode secrets: Use environment variables or key stores.
Input validation: Sanitize and restrict inputs to prevent injection.
Rate limiting: Implement to prevent abuse and DoS attacks.

Error Handling

Use standard JSON-RPC error codes for clarity and debugging.
Respond with meaningful error messages and structured responses.

Monitoring & Logging

Use structured logging to stderr (does not interfere with protocol).
Monitor response times, error rates, and resource usage.

Scalability

Design stateless servers for horizontal scaling.
Use caching for frequently requested data.
Containerize with Docker for portability and deploy with Kubernetes for resilience.

Advanced Use Cases and Patterns

Integrate with Databases, CI/CD, Analytics

Create servers for querying databases, orchestrating CI/CD tasks, or generating analytics reports.
Use multi-server orchestration for complex workflows.

Performance Optimization

Use async frameworks (aiohttp, asyncio) for I/O-bound tasks.
Pool database connections and cache external API responses.

Next Steps: Grow Your MCP Ecosystem

Mastering MCP unlocks new automation and integration possibilities for your team:

Start simple with utility servers (file readers, calculators, API wrappers).
Gradually expand to business-critical integrations (databases, monitoring, workflow automation).
Join the MCP community; contribute servers and learn best practices.
Monitor, document, and iterate for long-term maintainability—and consider using Apidog for streamlined documentation and API collaboration.

💡 Want a powerful API testing suite that delivers beautiful documentation, boosts team productivity, and replaces Postman at a better price? Try Apidog for all-in-one API design, testing, and collaboration.

button