{"slug": "build-your-own-mcp-server-from-scratch", "title": "Build Your Own MCP Server from Scratch", "summary": "A developer has published a guide for building a Model Context Protocol (MCP) server from scratch using the bare JSON-RPC 2.0 protocol, bypassing common frameworks to give engineers full control over the wire format. The protocol relies on just three core request types—`initialize`, `tools/list`, and `tools/call`—transported over stdio or HTTP, with each tool defined by a JSON Schema that agents use to construct valid calls. By understanding the protocol at this level, developers gain advantages in debugging, portability across any language or runtime, and the ability to evolve with future MCP capabilities without requiring full rewrites.", "body_md": "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.\n\nMCP is a JSON-RPC 2.0 protocol. A client sends a request. Your server returns a response. Three request types power the core loop:\n\n`initialize`\n\n, handshake. Client and server exchange capabilities.\n\n`tools/list`\n\n, discovery. Server returns every tool it offers, each with a JSON Schema describing its inputs.\n\n`tools/call`\n\n, execution. Client names a tool and passes arguments. Server runs the handler and returns structured content.\n\nTransport 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.\n\nThat is the entire architecture. Everything else is error handling, schema validation, and ergonomics.\n\nMCP 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.\n\nKnowing the wire format gives you three advantages frameworks obscure:\n\n**Debugging** , when a tool call fails, you can read the raw JSON-RPC message and pinpoint the fault in seconds.\n\n**Portability** , any language, any runtime, any transport. Write a server in Bash if you want. The protocol is the contract.\n\n**Evolution**, MCP will add capabilities. Understanding the base protocol lets you adopt new features by extension, always, sidestepping full rewrites.\n\nForge 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.\n\nArchonHQ is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.\n\nEvery message shares the same shape:\n\n```\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_weather\",\n    \"arguments\": { \"city\": \"Portland\" }\n  }\n}\n```\n\nThe response mirrors it:\n\n```\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"72°F, clear skies\" }\n    ]\n  }\n}\n```\n\nErrors swap `result`\n\nfor `error`\n\n:\n\n```\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"error\": {\n    \"code\": -32602,\n    \"message\": \"Invalid params: missing 'city'\"\n  }\n}\n```\n\nThree fields matter: `jsonrpc`\n\n(always `\"2.0\"`\n\n), `id`\n\n(correlates request to response), and `method`\n\n(the dispatch key).\n\nEach tool advertises itself through a JSON Schema object. A well-designed schema is the difference between a tool agents use and one they fumble.\n\n```\n{\n  \"name\": \"get_weather\",\n  \"description\": \"Retrieve current weather for a given city\",\n  \"inputSchema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"city\": {\n        \"type\": \"string\",\n        \"description\": \"City name, e.g. Portland\"\n      }\n    },\n    \"required\": [\"city\"]\n  }\n}\n```\n\nRules for effective schemas:\n\nMark every required parameter in `required`\n\n. Agents rely on this to construct valid calls.\n\nAdd `description`\n\nto each property. The agent reads descriptions to decide *which* tool to invoke and *what* values to pass.\n\nUse `enum`\n\nfor constrained values. This prevents hallucinated inputs.\n\nKeep schemas flat. Nested objects are valid but harder for agents to populate correctly.\n\nYour server runs a loop:\n\nStep Action 1 Read a JSON-RPC line from stdin 2 Parse the `method`\n\n3 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\n\nIn Python with asyncio:\n\n``` python\nasync def handle_message(message):\n    method = message.get(\"method\")\n    if method == \"initialize\":\n        return {\"capabilities\": {\"tools\": {}}}\n    elif method == \"tools/list\":\n        return {\"tools\": list_tools()}\n    elif method == \"tools/call\":\n        return await call_tool(message[\"params\"])\n    else:\n        return {\"error\": {\"code\": -32601, \"message\": f\"Method {method} unseen\"}}\n```\n\nStart with the `mcpbuild`\n\nCLI. Run `mcpbuild init my-server`\n\nand you get a project scaffold:\n\n```\nmy-server/\n  pyproject.toml\n  server.py\n  tools/\n    __init__.py\n```\n\n`server.py`\n\ncontains the JSON-RPC read loop and dispatch table. Each tool is a function registered by name. The `add-tool`\n\ncommand generates a stub handler and appends the tool schema to the registry. The `run`\n\ncommand boots the server on stdio (default) or HTTP transport.\n\nThe full CLI ships with this article. Download it, make it executable, and build your first MCP server in minutes.\n\nFeed this prompt a server concept. Get back a complete specification ready for implementation.\n\n```\n<prompt>\n<role>You are an MCP Server Architect. You produce complete MCP server specifications from a concept description.</role>\n<input>\n{{SERVER_CONCEPT}}\n</input>\n<output_format>\nReturn a specification with these sections:\n\n1. **Server Identity**: name, version, description\n2. **Tools**: For each tool, provide:\n   - name (snake_case)\n   - description (one sentence, action verb)\n   - inputSchema (valid JSON Schema, flat preferred)\n   - output shape (content types returned)\n   - error cases (expected failure modes)\n3. **Transport**: stdio or HTTP with rationale\n4. **Auth**: required or none; if required, specify mechanism (API key header, OAuth scope, etc.)\n5. **Error Handling Strategy**: per-tool error codes, fallback behavior, logging approach\n</output_format>\n<constraints>\n- Every tool must have a description an agent can use for tool selection.\n- Every inputSchema must include property-level descriptions.\n- Prefer enum constraints over free-text where values are bounded.\n- Transport choice must include latency and deployment context rationale.\n- 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.\n</constraints>\n</prompt>\n```\n\nThe `mcpbuild`\n\nCLI scaffolds, runs, and validates MCP servers from the terminal. Five commands cover the full lifecycle:\n\nCommand Description `init <name>`\n\nScaffold a new MCP server project with `pyproject.toml`\n\n, `server.py`\n\n, and tool stubs `add-tool`\n\nInteractive: enter tool name, description, and input schema JSON; generates a handler stub and registers the tool `run`\n\nStart the server (defaults to stdio transport; pass `--transport http --port 8080`\n\nfor HTTP) `validate`\n\nCheck the server against the MCP spec: tool schemas are valid JSON Schema, error handlers exist for every tool, transport config is sound `test`\n\nSend test `tools/list`\n\nand `tools/call`\n\nmessages to a running server and verify responses match the spec\n\nDownload the full implementation below. Single file, zero dependencies beyond the standard library and asyncio.\n\n```\n# Download\ncurl -O https://drive.google.com/file/d/1b1WFnBv0ZYcgQEW8KIVOKQtDzEKjPotm/view?usp=drive_link\nchmod +x mcpbuild.py\n\n# Scaffold a project\n./mcpbuild.py init weather-server\n\n# Add a tool interactively\ncd weather-server\n../mcpbuild.py add-tool\n\n# Run on stdio\n../mcpbuild.py run\n\n# Validate\n../mcpbuild.py validate\n\n# Test against a running server\n../mcpbuild.py test\n```\n\nThe 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.\n\nMCP 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`\n\n, `tools/list`\n\n, `tools/call`\n\n) and you stay safe.\n\nStdio 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.\n\nSchema validation is your first line of defense. Validate every incoming `tools/call`\n\nagainst the tool’s `inputSchema`\n\nbefore the handler runs. Reject early with a `-32602`\n\nInvalid params error. This prevents malformed data from reaching your business logic.\n\nForge 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.\n\nThe best MCP server is the one you can explain on a whiteboard. Tool schema in, content out. Everything else is detail.\n\n*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.*\n\n--- *This article was originally published on ArchonHQ — practical AI that wins every day. Subscribe free to get new articles in your inbox.*", "url": "https://wpnews.pro/news/build-your-own-mcp-server-from-scratch", "canonical_source": "https://dev.to/michal_szalinski_91bf893d/build-your-own-mcp-server-from-scratch-2mn7", "published_at": "2026-06-05 00:04:01+00:00", "updated_at": "2026-06-05 00:41:53.713230+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "artificial-intelligence", "large-language-models"], "entities": ["MCP", "JSON-RPC"], "alternates": {"html": "https://wpnews.pro/news/build-your-own-mcp-server-from-scratch", "markdown": "https://wpnews.pro/news/build-your-own-mcp-server-from-scratch.md", "text": "https://wpnews.pro/news/build-your-own-mcp-server-from-scratch.txt", "jsonld": "https://wpnews.pro/news/build-your-own-mcp-server-from-scratch.jsonld"}}