# Build Your Own MCP Server from Scratch > Source: > Published: 2026-06-05 00:04:01+00:00 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. 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. 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. 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). 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. 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: ``` python 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"}} ``` 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. Feed this prompt a server concept. Get back a complete specification ready for implementation. ``` You are an MCP Server Architect. You produce complete MCP server specifications from a concept description. {{SERVER_CONCEPT}} 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 - 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. ``` The `mcpbuild` CLI scaffolds, runs, and validates MCP servers from the terminal. Five commands cover the full lifecycle: Command Description `init ` 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. 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. 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.* --- *This article was originally published on ArchonHQ — practical AI that wins every day. Subscribe free to get new articles in your inbox.*