# first-mcp-server

The smallest MCP server that actually does something — one tool, stdio transport,
no build step. About 35 lines in `server.ts`.

I wrote this while figuring out how MCP works. If you've read
[Understanding MCP Servers](https://iamkuldeep.vercel.app/writings/understanding-mcp-servers),
this is that post's weather example as code you can actually run.

## What it does

Exposes a single tool, `getCityWeather`, over stdio. Ask Claude "what's the
weather in Delhi?" and it discovers the tool, calls it, and answers from the
result.

The weather itself is a hardcoded map of three cities. That's on purpose — the
point here is the protocol, not the data. Swap the lookup for a real API call
and nothing else about the server changes.

## Run it

```bash
npm install
npm start
```

That starts the server on stdio. On its own it does nothing visible — it's
waiting for a client to talk to it, which is the whole idea.

## Connect it to Claude

Add it to your MCP config (`claude_desktop_config.json` for Claude Desktop, or
`.mcp.json` for Claude Code):

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

Use an absolute path — the host spawns this as a subprocess and won't be in your
project directory. Restart the host, then ask it about the weather in Delhi,
Mumbai or Bangalore.

## The three pieces

Everything in `server.ts` is one of these:

| Piece | What it is |
|---|---|
| `McpServer` | the server itself, with a name and version the client sees |
| `registerTool` | one tool — a name, a description, and an input schema |
| `StdioServerTransport` | how bytes move; JSON-RPC over stdin/stdout |

The description and schema matter more than they look. They're the only thing
the model reads when deciding whether this tool is relevant to your question, so
vague descriptions produce a tool that never gets called.

## License

MIT