Build Your Own MCP Server from Scratch

Every AI agent ships with the same bottleneck: it can only reason over what it can reach. MCP servers dissolve that boundary. They expose tools, resources, and prompts to any compliant client over a JSON-RPC wire format so lean you can implement it in an afternoon. Yet most developers grab a framework, copy a template, and ship something they can barely debug. Forge starts differently. You will build an MCP server from the bare protocol up, understand every byte on the wire, and gain the mental model that makes every future server trivial.

The Idea (60 Seconds)

MCP is a JSON-RPC 2.0 protocol. A client sends a request. Your server returns a response. Three request types power the core loop:

• initialize, handshake. Client and server exchange capabilities.

• tools/list, discovery. Server returns every tool it offers, each with a JSON Schema describing its inputs.

• tools/call, execution. Client names a tool and passes arguments. Server runs the handler and returns structured content.

Transport is either stdio (JSON-RPC over stdin/stdout) or HTTP (Streamable HTTP). Stdio is the simplest place to start: read a line from stdin, parse it, dispatch, write a line to stdout.

That is the entire architecture. Everything else is error handling, schema validation, and ergonomics.

Why This Matters

MCP servers are the new APIs. Where REST gave machines endpoints, MCP gives agents tools with typed inputs and structured outputs. Every integration layer from IDE assistants to autonomous workflows converges on this protocol. The standard is young. The primitives are stable. The surface area is small enough to hold in your head all at once.

Knowing the wire format gives you three advantages frameworks obscure:

• Debugging , when a tool call fails, you can read the raw JSON-RPC message and pinpoint the fault in seconds.

• Portability , any language, any runtime, any transport. Write a server in Bash if you want. The protocol is the contract.

• Evolution, MCP will add capabilities. Understanding the base protocol lets you adopt new features by extension, always, sidestepping full rewrites.

Forge articles build on this foundation. If you understand the three core requests and the JSON-RPC envelope, every subsequent pattern is just a new handler.

ArchonHQ is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Walkthrough

The JSON-RPC Envelope

Every message shares the same shape:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "Portland" }
  }
}

The response mirrors it:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "72°F, clear skies" }
    ]
  }
}

Errors swap result for error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: missing 'city'"
  }
}

Three fields matter: jsonrpc (always "2.0"), id (correlates request to response), and method (the dispatch key).

Tool Schema Design

Each tool advertises itself through a JSON Schema object. A well-designed schema is the difference between a tool agents use and one they fumble.

{
  "name": "get_weather",
  "description": "Retrieve current weather for a given city",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name, e.g. Portland"
      }
    },
    "required": ["city"]
  }
}

Rules for effective schemas:

• Mark every required parameter in required. Agents rely on this to construct valid calls.

• Add description to each property. The agent reads descriptions to decide which tool to invoke and what values to pass.

• Use enum for constrained values. This prevents hallucinated inputs.

• Keep schemas flat. Nested objects are valid but harder for agents to populate correctly.

The Request Lifecycle

Your server runs a loop:

Step Action 1 Read a JSON-RPC line from stdin 2 Parse the method 3 Dispatch to the matching handler 4 Handler returns a result or raises an error 5 Serialize the response to JSON 6 Write it to stdout

In Python with asyncio:

async def handle_message(message):
    method = message.get("method")
    if method == "initialize":
        return {"capabilities": {"tools": {}}}
    elif method == "tools/list":
        return {"tools": list_tools()}
    elif method == "tools/call":
        return await call_tool(message["params"])
    else:
        return {"error": {"code": -32601, "message": f"Method {method} unseen"}}

Building the Server

Start with the mcpbuild CLI. Run mcpbuild init my-server and you get a project scaffold:

my-server/
  pyproject.toml
  server.py
  tools/
    __init__.py

server.py contains the JSON-RPC read loop and dispatch table. Each tool is a function registered by name. The add-tool command generates a stub handler and appends the tool schema to the registry. The run command boots the server on stdio (default) or HTTP transport.

The full CLI ships with this article. Download it, make it executable, and build your first MCP server in minutes.

The Prompt Toolkit

MCP Server Architect Prompt

Feed this prompt a server concept. Get back a complete specification ready for implementation.

<prompt>
<role>You are an MCP Server Architect. You produce complete MCP server specifications from a concept description.</role>
<input>
{{SERVER_CONCEPT}}
</input>
<output_format>
Return a specification with these sections:

1. **Server Identity**: name, version, description
2. **Tools**: For each tool, provide:
   - name (snake_case)
   - description (one sentence, action verb)
   - inputSchema (valid JSON Schema, flat preferred)
   - output shape (content types returned)
   - error cases (expected failure modes)
3. **Transport**: stdio or HTTP with rationale
4. **Auth**: required or none; if required, specify mechanism (API key header, OAuth scope, etc.)
5. **Error Handling Strategy**: per-tool error codes, fallback behavior, logging approach
</output_format>
<constraints>
- Every tool must have a description an agent can use for tool selection.
- Every inputSchema must include property-level descriptions.
- Prefer enum constraints over free-text where values are bounded.
- Transport choice must include latency and deployment context rationale.
- Error codes must use JSON-RPC standard codes where applicable (-32600, -32601, -32602) and custom codes in the -32000 to -32099 range for server-specific errors.
</constraints>
</prompt>

mcpbuild CLI

The mcpbuild CLI scaffolds, runs, and validates MCP servers from the terminal. Five commands cover the full lifecycle:

Command Description init <name> Scaffold a new MCP server project with pyproject.toml, server.py, and tool stubs add-tool Interactive: enter tool name, description, and input schema JSON; generates a handler stub and registers the tool run Start the server (defaults to stdio transport; pass --transport http --port 8080 for HTTP) validate Check the server against the MCP spec: tool schemas are valid JSON Schema, error handlers exist for every tool, transport config is sound test Send test tools/list and tools/call messages to a running server and verify responses match the spec

Download the full implementation below. Single file, zero dependencies beyond the standard library and asyncio.

# Download
curl -O https://drive.google.com/file/d/1b1WFnBv0ZYcgQEW8KIVOKQtDzEKjPotm/view?usp=drive_link

chmod +x mcpbuild.py

# Scaffold a project
./mcpbuild.py init weather-server

# Add a tool interactively
cd weather-server
../mcpbuild.py add-tool

# Run on stdio
../mcpbuild.py run

# Validate
../mcpbuild.py validate

# Test against a running server
../mcpbuild.py test

The CLI is a single Python file. Read it, modify it, make it yours. It uses raw JSON-RPC over stdio so you see exactly what flows between client and server.

Caveats

MCP is evolving. The spec adds capabilities and the reference implementations shift. The wire format is stable, but higher-level features like sampling, elicitation, and structured logging may change. Build on the core three methods (initialize, tools/list, tools/call) and you stay safe.

Stdio transport pairs with process-based hosting (Claude Desktop, IDE extensions). HTTP transport pairs with remote hosting. Pick the one that matches your deployment. Mixing both in one server adds complexity best reserved for later.

Schema validation is your first line of defense. Validate every incoming tools/call against the tool’s inputSchema before the handler runs. Reject early with a -32602 Invalid params error. This prevents malformed data from reaching your business logic.

Philosophy

Forge believes in building on the protocol, around it. Frameworks accelerate while protocols ground. When you understand the JSON-RPC message format, the dispatch table, and the schema contract, frameworks become optional convenience rather than required dependency, letting you debug faster, ship leaner, and adapt when the spec evolves.

The best MCP server is the one you can explain on a whiteboard. Tool schema in, content out. Everything else is detail.

This is F01 in the ArchonHQ Forge Series. The next article, F02, covers tool schema design patterns that make agents invoke your tools correctly on the first try. Subscribe to ArchonHQ to unlock every Forge article, CLI tool, and prompt kit.

Subscribe now

--- This article was originally published on ArchonHQ — practical AI that wins every day. Subscribe free to get new articles in your inbox.