How to Build Your First MCP Server with Claude Code (2026 Guide)

mcp-builder by anthropics (75,898 installs, 147,832 GitHub stars — skills.sh registry) is the #1 skill for building MCP servers with Claude Code. It teaches the full server scaffolding pattern: tool definitions, input schemas, handler functions, and error responses — everything needed to ship an MCP server in under an hour. The MCP ecosystem reached 97 million monthly SDK downloads and 5,800+ servers by mid-2026; every major AI platform (Anthropic, OpenAI, Google, GitHub, Vercel) now ships first-party MCP support.

What is an MCP server and why should you build one?

Model Context Protocol (MCP) is the standard interface for connecting AI agents to external tools and data sources. An MCP server exposes capabilities as typed "tools" that any MCP-compatible agent can call.

If you have a:

• Database — an MCP server gives Claude Code direct query access without copy-pasting schema.
• REST API — an MCP server wraps auth, pagination, and rate-limiting so Claude Code calls get_customer(id) not raw HTTP.
• CLI tool — an MCP server converts commands to structured tool calls with typed inputs/outputs.
• Internal system — an MCP server brings proprietary data into Claude Code's context without exporting files.

The mcp-builder skill (75,898 installs) teaches Claude Code to generate all of this from a brief tool description.

How does Claude Code scaffold an MCP server?

With mcp-builder loaded, describe what your server should do:

"Build an MCP server that connects to a PostgreSQL database and exposes tools: query_table, list_tables, and describe_schema."

Claude Code generates a TypeScript MCP server using the @modelcontextprotocol/sdk package:

```typescript 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: "postgres-mcp", version: "1.0.0" });

server.tool("query_table", { table: z.string(), where: z.string().optional(), limit: z.number().default(100), }, async ({ table, where, limit }) => { // handler logic return { content: [{ type: "text", text: JSON.stringify(results) }] }; });

const transport = new StdioServerTransport(); await server.connect(transport); ```

The pattern — McpServer, server.tool(), Zod schemas, StdioServerTransport — is what mcp-builder encodes.

Which MCP server skills are available in the catalog?

Top MCP-building skills by installs:

• `mcp-builder` by anthropics — 75,898 installs, 147,832 GitHub stars. Full MCP server scaffolding with tool definitions, Zod schemas, error handling, and transport setup.
• `supabase` by supabase — 125,873 installs, 2,207 GitHub stars. Builds on MCP; gives Claude Code a Supabase MCP server for database queries, auth, and storage operations.
• `neon-postgres` by neondatabase — 42,036 installs. Postgres-specific MCP patterns; serverless connection handling via Neon's HTTP transport.
• `skill-creator` by anthropics — 273,339 installs, 147,832 GitHub stars. Creates Claude Code skills (markdown-based) rather than full MCP servers; the right choice when you want to teach Claude Code a workflow rather than connect an external system.

For MCP server development specifically, mcp-builder is the primary skill.

What is the difference between an MCP server and a Claude Code skill?

| | MCP Server | Claude Code Skill | |---|---|---| | Format | TypeScript/Python server | Markdown file | | Runs | As a separate process | Inside Claude Code context | | Best for | External tools, databases, APIs | Workflow instructions, coding patterns | | Build with | mcp-builder (75,898 installs) | skill-creator (273,339 installs) | | Transport | stdio, HTTP/SSE | Not applicable |

Use an MCP server when you need Claude Code to take actions in or retrieve data from an external system at runtime. Use a skill when you want to change how Claude Code writes code or approaches a problem.

What languages and frameworks can I use to build MCP servers?

MCP servers can be built in any language — the protocol is transport-agnostic. The two official SDKs:

1. TypeScript (@modelcontextprotocol/sdk) — the most common; mcp-builder generates TypeScript by default. 2. Python (mcp) — preferred for data science and ML tooling.

Additional community SDKs exist for Go, Rust, Java, C#, and Ruby. The mcp-builder skill handles TypeScript; for Python, ask Claude Code to translate the generated scaffold to Python with the mcp package.

Transport options:

• stdio — simplest; Claude Code spawns the server as a child process. Best for local development.
• HTTP/SSE — required for remote servers; supports load balancers via Mcp-Method and Mcp-Name headers (added in the 2026 MCP spec).

How do I publish and distribute an MCP server?

1. Local only: Add to claude mcp add <name> <command> — no publishing required. 2. Team use: Push to a private registry or internal npm/GitHub Packages. 3. Public: Submit to the MCP registry at modelcontextprotocol.io — the catalog of 5,800+ servers. 4. skills.sh: If your MCP server has an accompanying Claude Code skill (usage instructions), submit it at skills.sh for discovery by 91.5 M total install events.

The directory-submissions skill by coreyhaines31 (30,960 installs, 32,419 GitHub stars) automates submission to directories including the MCP registry.

Key takeaways

• mcp-builder by anthropics (75,898 installs, 147,832 GitHub stars) is the #1 skill for scaffolding MCP servers with Claude Code — it generates tool definitions, Zod schemas, and transport setup in a single prompt.
• MCP servers connect Claude Code to external systems at runtime; skills teach Claude Code patterns in context. Use mcp-builder for the former, skill-creator (273,339 installs) for the latter.
• The MCP ecosystem reached 97 million monthly SDK downloads and 5,800+ servers by mid-2026, with Anthropic, OpenAI, Google, GitHub, and Vercel all shipping first-party MCP support.
• Use stdio transport for local development; HTTP/SSE transport for remote or team-shared servers.
• The skills.sh catalog has 100+ MCP-tagged skills out of 25,215 total listings; the top four MCP-related skills total 517,808 combined installs (skills.sh registry, GitHub).

Common questions