MCP Server for Claude Code Tutorial [Deep Dive] [2026]

Why MCP Matters for Claude Code

Model Context Protocol, or MCP, is the interface layer that lets AI coding tools call external capabilities in a predictable way. In Claude Code, an MCP server can expose tools, prompts, resources, and event channels so the agent can do more than edit local files. It can query a database, hit an internal API, fetch release notes, or run a carefully bounded utility you wrote yourself.

For a fast first build, the right target is a local stdio server. Claude Code starts your process, exchanges JSON-RPC messages over standard input and output, and discovers the tools your server exposes. That means you can ship something useful without deploying infrastructure first.

This walkthrough uses the current Claude Code MCP flow documented by Anthropic and the core MCP SDK patterns from the protocol project. By the end, you will have a working local server with two tools, register it in Claude Code, and verify that the tools are callable in a real session.

Key takeaway

If your goal is to get Claude Code talking to a custom capability today, start with a local stdio MCP server in TypeScript. It is the smallest path from idea to usable tool, and you can later promote the same capability into a shared project config or remote service.

Prerequisites

You need the following before you start:

Node.js 20 or newer
npm available on your path
Claude Code installed and working from your terminal
A local project directory where you can run `npx` commands
Basic familiarity with TypeScript and command-line tooling

Time budget: about 30 minutes if your Node environment is already healthy.

Why this stack: TypeScript gives you readable examples, `tsx` avoids a compile loop during setup, and `zod` makes tool input validation explicit. If you want to inspect or prettify your server responses while iterating, TechBytes' Code Formatter is useful for cleaning up JSON payloads before you wire them into tests or docs.

References: Claude Code MCP setup is covered in the official docs at code.claude.com/docs/en/mcp, and the protocol itself lives at modelcontextprotocol.io.

Build the Server

1. Scaffold a minimal project
Create a fresh folder and install the runtime and development dependencies.
```
mkdir claude-mcp-demo
cd claude-mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
npx tsc --init
```
This is enough to run a local server directly with `tsx`. You do not need bundling, Docker, or a hosted endpoint for the first pass.

2. Add a small MCP server with two tools

Create `src/index.ts` and expose a pair of utilities Claude can call: one counts words and one slugifies a title. Keep the output simple and textual at first.

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: 'techbytes-demo',
  version: '1.0.0'
});

server.tool(
  'word_count',
  {
    text: z.string().min(1)
  },
  async ({ text }) => {
    const count = text.trim().split(/\s+/).filter(Boolean).length;

    return {
      content: [
        {
          type: 'text',
          text: `Word count: ${count}`
        }
      ]
    };
  }
);

server.tool(
  'slugify_title',
  {
    title: z.string().min(1)
  },
  async ({ title }) => {
    const slug = title
      .toLowerCase()
      .trim()
      .replace(/[^a-z0-9\s-]/g, '')
      .replace(/\s+/g, '-')
      .replace(/-+/g, '-');

    return {
      content: [
        {
          type: 'text',
          text: slug
        }
      ]
    };
  }
);

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

console.error('techbytes-demo MCP server is running');

Two implementation details matter here. First, the tool schemas are explicit, so Claude gets a clean contract for each call. Second, logging goes to stderr with `console.error`. Do not write debug logs to stdout, because stdout is carrying the MCP protocol messages.

3. Sanity-check the server locally
Before you register anything with Claude Code, make sure the process starts without import or runtime errors.
```
npx tsx src/index.ts
```
You should not expect a chatty terminal. A quiet process is normal because it is waiting for a client to connect over stdio. If you see the stderr line and the process remains alive, you are in good shape. Stop it with `Ctrl+C` before the next step.
4. Register the server with Claude Code
Claude Code's current syntax for local stdio servers is `claude mcp add [options] <name> -- <command> [args...]`. Use an absolute path so the registration is stable from any shell location.
```
claude mcp add --transport stdio --scope local techbytes-demo -- \
  npx tsx /absolute/path/to/claude-mcp-demo/src/index.ts
```
Scope choice matters: `local` is the default and keeps the config private to you in the current project context. If you want the team to share the server, use `--scope project` so Claude Code writes a `.mcp.json` file at the repo root.
A project-scoped config will look roughly like this:
```
{
  "mcpServers": {
    "techbytes-demo": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/claude-mcp-demo/src/index.ts"],
      "env": {}
    }
  }
}
```
If you plan to check that file into source control, avoid embedding secrets directly. For demo payloads or sample API responses, sanitize them before publishing. TechBytes' Data Masking Tool is a practical cleanup step when your examples contain customer-like fields.
5. Ask Claude to use the tools
Now start Claude Code in the same workspace and verify the server is visible. You can inspect server state with the slash command or go straight to a prompt that invokes a tool naturally.
```
/mcp
```
```
Use the word_count tool on this text: "MCP servers give Claude structured access to external tools."
```
```
Use the slugify_title tool for: "How to Build an MCP Server for Claude Code in 30 Minutes"
```
The exact display format depends on the Claude Code surface, but the important behavior is that the tools are discovered and callable without manual wiring inside the conversation.

Verification and Expected Output

There are three fast checks that tell you whether the server is working end to end.

Run `claude mcp list` in your terminal. You should see `techbytes-demo` listed with a stdio transport.
Run `/mcp` inside Claude Code. The server should appear as connected or available for the current session.
Call each tool once from a prompt. `word_count` should return a numeric count, and `slugify_title` should return a lowercase hyphenated slug such as `how-to-build-an-mcp-server-for-claude-code-in-30-minutes`.

If all three checks pass, your server is correctly registered, launches cleanly, and exposes tools Claude can actually use.

Troubleshooting Top 3

1. The server exits immediately

This is usually a runtime problem rather than an MCP problem. Common causes include a missing dependency, the wrong Node version, or a path that works only from one directory. Re-run `npx tsx src/index.ts` directly and fix that first. If you printed debug output with `console.log`, move it to `console.error` so stdout stays protocol-safe.

2. Claude Code shows the server, but the tools do not appear

Check the registration command carefully. In the current CLI syntax, all Claude flags must come before the server name, and the double dash must come before the actual command. Also verify you added a stdio server, not an HTTP or SSE transport by mistake. Finish by checking `/mcp` again after restarting the session.

3. The setup works on your machine but fails for teammates

This is a scope and path issue. Local scope is private by design, and hardcoded absolute paths often break across machines. Move to `--scope project`, commit the generated `.mcp.json`, and use environment-variable expansion where needed. Keep credentials out of the file and inject them through `env` instead.

What's Next

Once the basic server works, the next upgrade is not more code. It is better boundaries. Add tools only where Claude genuinely needs an external action. Keep inputs typed, outputs compact, and failure messages explicit. That makes the server safer to run and easier to debug.

From here, the natural next steps are to add resources for read-only context, package the server into a reusable project config, or move from local stdio to an HTTP transport when you want a shared remote service. If your team is using Claude Code broadly, that is where an ad hoc utility turns into real platform surface area.

The 30-minute version is enough to prove the model: Claude Code can discover your server, validate tool inputs, and call your code through MCP today. After that, the engineering work shifts from setup to product thinking: what capability deserves to be a tool, who owns it, and how tightly you want to control its side effects.