Write your first MCP server and wire it to Claude

Tool calling ties your tools to one application's codebase. The Model Context Protocol (MCP) breaks that coupling: you expose tools, resources, and prompts through a standard server, and any MCP client — Claude Desktop, an IDE, or your own agent — can use them without bespoke glue. In this tutorial you build a small MCP server in TypeScript, verify it with the Inspector, and wire it to Claude.

Our server will expose one tool, get_word_count, so the protocol stays in focus rather than the tool logic.

Prerequisites

• Node.js 20+ and npm.
• TypeScript basics and comfort running a local CLI.
• Claude Desktop installed (for the final wiring step), or any MCP client.
• About 25 minutes.

Expected outcome: a runnable MCP server (server.ts) that advertises one typed tool over stdio, passes a manual call in the MCP Inspector, and shows up as a usable tool inside Claude.

Scaffold the server project

Install the official MCP TypeScript SDK and a schema library for typed tool inputs.

mkdir wordcount-mcp && cd wordcount-mcp
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/sdk zod
npm install -D tsx typescript

The SDK gives you the server runtime and transports; zod describes tool inputs in a way the SDK turns into a JSON schema automatically.

Create the server and register a tool

An MCP server is an object you attach tools to, then connect to a transport. Create server.ts:

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

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

server.registerTool(
  "get_word_count",
  {
    title: "Word counter",
    description: "Count the words in a block of text. Use when asked how long or how many words a passage is.",
    inputSchema: { text: z.string().describe("The text to count words in.") },
  },
  async ({ text }) => {
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return { content: [{ type: "text", text: `Word count: ${count}` }] };
  },
);

The handler returns a content array — the same shape MCP uses everywhere. A tool can return multiple content blocks, but one text block is enough here.

Connect the stdio transport

The server needs a transport to speak over. For local development, stdio runs the server as a subprocess of the client and exchanges JSON-RPC messages over stdin/stdout. Append to server.ts:

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // IMPORTANT: log to stderr, never stdout.
  console.error("[wordcount] MCP server running on stdio");
}

main().catch((err) => {
  console.error("[wordcount] fatal:", err);
  process.exit(1);
});

> Heads up: on stdio, stdout is the protocol channel. A single console.log writes garbage into the JSON-RPC stream and the client drops the connection with a confusing parse error. Use console.error for every log line.

Make the server runnable as a command

MCP clients launch your server by running a command. Add a small build/run setup so the command is stable. The simplest reliable launch is through tsx:

// package.json (relevant fields)
{
  "type": "module",
  "bin": { "wordcount-mcp": "./server.ts" },
  "scripts": {
    "start": "tsx server.ts",
    "inspect": "npx @modelcontextprotocol/inspector tsx server.ts"
  }
}

The exact launch command — here tsx server.ts — is what you will hand to the client in Step 6, so keep it copy-pasteable.

Test with the MCP Inspector

Before involving a model, prove the server works with the Inspector, a local UI that speaks MCP directly.

npm run inspect

This opens a browser UI connected to your server. Click Tools -> List, select get_word_count, enter { "text": "the quick brown fox" }, and call it. You should get back Word count: 4.

> Heads up: if the Inspector shows "failed to parse message", you almost certainly logged to stdout somewhere. Re-check every log line is console.error, and that no dependency prints a banner to stdout on startup.

Wire the server into Claude

Now register the server with an MCP client. In Claude Desktop, open the config file and add your server under mcpServers:

// claude_desktop_config.json
{
  "mcpServers": {
    "wordcount": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/wordcount-mcp/server.ts"]
    }
  }
}

Use an absolute path — the client does not run from your project directory. Restart the client so it relaunches the server subprocess.

> Heads up: relative paths are the most common wiring failure. The client spawns your command from its own working directory, so ./server.ts will not be found. Always give the full path.

Verify your install

In a fresh Claude conversation, confirm the tool is available and call it through natural language:

You: How many words are in: "model context protocol makes tools reusable"?
Claude: (calls get_word_count) That passage has 6 words.

If Claude does not offer the tool, check three things in order: the config JSON is valid (a trailing comma silently disables it), the path is absolute, and the server starts cleanly under npm start without printing to stdout. The Inspector passing in Step 5 but Claude failing here almost always means a config or path problem, not a server bug.

Limitations and open questions

• stdio is single-client and local. It is perfect for development and desktop use, but for a shared or remote server you need the streamable HTTP transport and an auth story.
• No built-in authorization. The stdio server trusts whoever launched it. Multi-user deployments must add authentication at the transport layer.
• Schema drift is silent. If your zod schema and your handler disagree, you get confusing runtime errors rather than a compile-time failure. Keep them tight.
• Versioning is on you. As you add tools, clients cache capabilities. Bump the server version and document breaking changes so clients can adapt.

The open question worth tracking is hosting: running MCP servers remotely (auth, multi-tenancy, scaling the HTTP transport) is younger than the local stdio story, and best practices are still settling. For a first server, stdio plus the Inspector is the fastest path to a working, reusable tool.