How to Build an MCP Server (2026)

What an MCP server actually is

An MCP server is a small program that speaks the Model Context Protocol: JSON-RPC 2.0 messages over a transport, exposing three primitives to any compatible AI client. You never talk to the model — the host (Claude Desktop, Claude Code, Cursor, VS Code Copilot, ChatGPT connectors) runs one client per server and decides when to call you:

• Tools — executable functions the model calls to do things (create_ticket, query_database, run_scan). This is 90% of what you will build.
• Resources — read-only data the client can load as context: file contents, database schemas, API docs.
• Prompts — reusable, user-invoked templates (/summarize-pr, /generate-report).

Why bother? Because MCP became the agent-tool standard the fast way: monthly SDK downloads grew from roughly 97 million (December 2025, Anthropic's own ecosystem update) past 400 million (July 2026, per the spec-release announcement), with the official registry holding about 9,650 latest-version server records by May 2026 and roughly 15,900 public servers across four major registries by August 2026. Write one server and every MCP client in that ecosystem can call it.

Three things to internalize before writing code: tool descriptions are prompts (the model picks your tool based on the name and description alone, so “get the current forecast for a city” beats “weather tool” every time); on the stdio transport, stdout carries the protocol, so a stray console.log corrupts the stream — log to stderr; and return errors as results the model can read rather than crashing the connection, so the agent can self-correct.

Step 1 — Pick your transport: stdio or Streamable HTTP

This is the first real decision, and it is a business decision as much as a technical one. Protocol semantics are identical on both transports — a transport is a binding:

The structural fact most builders learn too late: a stdio/npm package runs on the buyer's machine, so no call ever passes through a meter — stdio listings cannot collect per-call revenue even on paid marketplaces. If monetization is anywhere in the plan, build for Streamable HTTP behind a public HTTPS endpoint. Roughly three quarters of tracked MCP servers are stdio-only, which is most of why so few ever earn anything (see our sell MCP servers breakdown).

Step 2 — Build your first tool

Use an official SDK — never roll your own JSON-RPC layer. Tier-1 SDKs are TypeScript, Python, C#, and Go. The minimal server is two files of boilerplate. TypeScript with the official SDK and Zod:

npm init -y && npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "task-server", version: "1.0.0" });

server.registerTool(
  "get_task",
  {
    title: "Get a task",
    description: "Fetch a task by ID from the team tracker.",
    inputSchema: {
      id: z.string().describe("The task ID, e.g. ENG-142"),
    },
    annotations: { readOnlyHint: true },
  },
  async ({ id }) => {
    const task = await db.tasks.find(id);        // your real data access
    return { content: [{ type: "text", text: JSON.stringify(task) }] };
  }
);

await server.connect(new StdioServerTransport());

The single most common TypeScript gotcha: inputSchema is a raw Zod shape — a plain object whose values are Zod types — not a z.object() wrapper. Passing a plain JSON Schema object instead silently registers the tool with an empty parameter schema: it compiles, it lists, and then no client can ever pass arguments to it (documented in the SDK's own issue tracker). Use Zod shapes for both inputSchema and outputSchema and this class of silent failure disappears.

Python is the same shape of work with decorators — the official Python SDK (the mcp package) and the popular FastMCP framework both generate tool schemas from type hints and docstrings:

# pip install fastmcp        (or: official `mcp` SDK)
from fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool
async def get_forecast(city: str) -> str:
    """Return the current forecast for a city."""
    return await real_api_call(city)

if __name__ == "__main__":
    mcp.run(transport="stdio")   # or transport="http" for remote

Name tools like github_create_issue — prefix plus action — because the model navigates hundreds of tools by name and description alone. Keep responses focused and paginated; oversized responses that blow the context window are a top reason hand-written servers fail agents quietly.

Step 3 — Test with MCP Inspector

The MCP Inspector is the reference test client, and it runs through npx with nothing installed (Node 22.19+ for the current release). It ships three clients on one binary — web, CLI, and TUI — all sharing the same connection core:

# Web UI (default)
npx @modelcontextprotocol/inspector node build/index.js

# Scriptable CLI for CI and pipelines
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name get_task --tool-arg id=ENG-142 --format json | jq .result

# Remote HTTP server
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp \
  --transport http --method tools/list

Work the loop: connect, verify tools/list shows every tool with a full schema, exercise each tool with valid and invalid inputs, and check the error messages — agents read your errors, so they should suggest the next step, not print a stack trace. The Inspector's exit codes even support CI: fail the build when a tool disappears from tools/list.

Step 4 — The errors that trip up almost everyone

The five failure modes behind most “my MCP server doesn't work” threads.

Step 4 — Connect a real client

Inspector green means the protocol works; a real host is the acceptance test. For Claude Desktop, point the config at your entry file with absolute paths:

// claude_desktop_config.json (macOS: ~/Library/Application Support/Claude;
// Windows: %APPDATA%\Claude)
{
  "mcpServers": {
    "tasks": {
      "command": "node",
      "args": ["C:/ABSOLUTE/path/to/tasks-mcp/build/index.js"]
    }
  }
}

Logs land in ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows). On Claude Code, claude mcp add does the same wiring from the terminal. Every client restart is required after config edits — a fully quit Claude Desktop, not a closed window.

Step 5 — Publish: package registry, then the official registry

Two-layer distribution: ship the artifact where developers install it, then list it in the official registry so agents can discover it. The registry stores metadata only — your code lives on npm, PyPI, or your own URL. The mcp-publisher CLI does the official listing:

# 1. Install the publisher CLI
brew install mcp-publisher        # or download from the registry repo

# 2. Prove you own the package
// package.json (npm)             # README (PyPI)
{ "mcpName":                      mcp-name: io.github.username/server-name
  "io.github.username/my-server" }

# 3. Authenticate + publish
mcp-publisher login github
mcp-publisher publish

Then list everywhere developers actually browse: Glama (submit the GitHub repo — it indexes tools and schemas and gives every listing an in-browser inspector session), Smithery, PulseMCP, mcp.so. Two rules from the ecosystem's own data: every tool needs a description (the field a model reads when deciding whether to call you — in one 288-tool sample, 100% of usable tools had one), and a focused server is normal — the median healthy server exposes four or five tools, not fifty.

For teams, deploy the HTTP variant like any web service: containerize, put it behind TLS, and — because the 2026-07-28 spec made the protocol stateless — any instance behind a plain round-robin load balancer can serve any request. No session store, no sticky routing.

Build against the 2026-07-28 spec, not the tutorials

The July 2026 spec revision is the biggest architectural change since MCP launched: the protocol core went stateless. If your code (or a tutorial you are copying) assumes the old handshake, it is building against a deprecation clock — the spec now carries a formal 12-month minimum deprecation window:

Most existing local tooling is unaffected — the stateless shift mainly matters for remote deployments, where it removes the hardest scaling problem the old session model created.

MCP Apps: give your tools an interface

The protocol's first official extension, MCP Apps (SEP-1865, ratified January 26, 2026 by Anthropic, OpenAI, and the MCP-UI maintainers) lets a tool return a working interface instead of a text summary. The mechanics are small: register an HTML resource under a ui:// URI with the text/html+mcp MIME type, point the tool's metadata at it, and the host renders it in a sandboxed iframe that talks back over JSON-RPC on postMessage:

// Tool references its UI in metadata
{
  name: "visualize_data_as_bar_chart",
  inputSchema: { /* ... */ },
  _meta: { "ui/resourceUri": "ui://charts/bar-chart" }
}

ChatGPT, Claude, VS Code Copilot, Cursor, Goose, and Postman all ship support, with Amplitude, Asana, Box, Canva, Figma, Salesforce, and Slack among the launch partners — making it the most widely implemented official extension. If your tool returns anything a human looks at — a chart, a form, a diff — returning the interface beats describing it in prose. This is also where VibeFuse lives natively: the same widget-as-interface idea is the core of the free harness, and marketplace widgets, skills, and styling packs install into it with one click.

Security: the part that will bite you

Two different jobs get called “securing an MCP server.” The first is transport auth for hosted servers: your server is an OAuth 2.1 resource server — it verifies tokens and never issues them. On the first unauthenticated call, return 401 with a WWW-Authenticate header pointing at your RFC 9728 Protected Resource Metadata document; the client walks 401 → metadata → authorization server → token → retry, with no custom code. Note what this does not cover: none of it protects stdio, which runs with the local user's full permissions by design.

The second is supply-chain trust, and it cuts both ways — for your users and for your own machine. Tool poisoning embeds adversarial instructions in tool descriptions or responses (OWASP's MCP Top 10 lists it as a top attack class), and the rug pull — silently changing a tool's definition after approval — is a catalogued vulnerability (CVE-2025-54136, CVSS 8.8, in a major IDE, patched July 2025). Defensive baseline that costs an afternoon: hash-pin your tool definitions at approval time, keep a server allowlist, treat all tool-returned content as untrusted data, and run mcp-scan against your own configuration. If you build with agents in the loop, our vibe coding security checklist covers the adjacent ground.

Where VibeFuse fits

Building is step one; running is every day after. VibeFuse is a free Windows harness where Settings → Tools hosts branded MCP cards (Google Workspace, Drive, GitHub, Copilot, Discord, Linear) plus your custom servers — every connected tool exposed to the built-in agents, no separate MCP host to babysit. That makes every install a potential user for whatever you build.

And if the server you just built is the product: the VibeFuse marketplace is the open-source layer where creators make money on what they build — a flat 80% revenue share via Stripe Connect, $0.50–$500 creator-set pricing, no listing fee — inside the first ever free widget-based AI harness. Local/offline processing, works in any app.

Explore VibeFuse & harness guides

• Harness Guide
• Free Coding Tools
• AI Coding Agent Desktop
• Free Voice Transcription
• Free Text to Speech
• VibeFuse Product
• Widget Marketplace
• Download Free
• VibeFuse Docs
• Shareable AI Widgets
• Shareable AI Skills
• MCP Tools
• AI Agent Harness
• Harness Engineering
• HyperFrames Video
• Skill Seekers
• Sell AI Skills
• AI Skills Marketplace Compared
• Cursor Alternative
• Local Whisper + Piper
• Custom AI Dashboard
• Community Hub