mcp-hello-world

A learning-focused MCP server that demonstrates how the Model Context Protocol works.

What is MCP?

MCP (Model Context Protocol) is a standard that lets AI assistants like Claude use external tools. Think of it like a plugin system:

1. You build a server that offers tools
2. Claude connects to your server
3. Claude can now call your tools during conversations

This project is a minimal example with two tools that show a learning progression.

What Does This Server Do?

It has two tools:

Tool	Input	Output	Purpose
hello	(none)	world	Minimal static example
polyglot	A greeting in any language	Structured JSON with language info	Shows LangChain + structured output

The hello tool is intentionally simple - it's about understanding how MCP works. The polyglot tool builds on that by calling an external LLM.

Project Structure

mcp-hello-world/
├── src/
│   └── index.ts                      # The MCP server
├── docs/
│   ├── langchain-polyglot-tool.md    # LangChain basics
│   └── structured-output.md          # Structured output with Zod
├── dist/                             # Compiled JavaScript (generated by build)
├── package.json                      # Project dependencies
└── tsconfig.json                     # TypeScript configuration

How to Build

npm install    # Install dependencies
npm run build  # Compile TypeScript to JavaScript

How to Use With Claude

To connect this server to Claude, add it to your MCP configuration.

For Claude Code (CLI):

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hello-world": {
      "command": "node",
      "args": ["/full/path/to/mcp-hello-world/dist/index.js"]
    }
  }
}

For Claude Desktop App:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "hello-world": {
      "command": "node",
      "args": ["/full/path/to/mcp-hello-world/dist/index.js"]
    }
  }
}

After adding the configuration, restart Claude. The hello tool will be available.

How MCP Communication Works

┌─────────────────┐         ┌─────────────────┐
│                 │  stdin  │                 │
│     Claude      │────────▶│   MCP Server    │
│                 │◀────────│                 │
│                 │ stdout  │                 │
└─────────────────┘         └─────────────────┘

1. Claude launches the server as a subprocess
2. Claude sends JSON messages to the server via stdin
3. The server processes requests and sends responses via stdout
4. This back-and-forth follows the MCP protocol specification

Key Concepts

Server

The main object that manages everything. It:

• Registers available tools
• Handles incoming requests
• Routes tool calls to handler functions

Tool

A function that Claude can call. Each tool has:

• Name: How Claude identifies it (e.g., "hello")
• Description: Helps Claude know when to use it
• Parameters: What inputs it accepts (our tool has none)
• Handler: The code that runs when called

Transport

How the server communicates. We use StdioServerTransport which means:

• Input comes from stdin
• Output goes to stdout
• Claude runs the server as a subprocess

This is the standard approach for local MCP servers.

The Polyglot Tool

The polyglot tool demonstrates LangChain's structured output feature. Send a greeting in any language, get back validated JSON with language details.

Input:

"bonjour"

Output:

{
  "detectedLanguage": "French",
  "greeting": "bonjour",
  "worldTranslation": "monde",
  "languageFamily": "Romance"
}

Requirements: The polyglot tool needs an ANTHROPIC_API_KEY environment variable. This project uses Teller to inject secrets:

teller run -- npm start

Greetings for Testing

The worldTranslation field in the response:

Language	Greeting	worldTranslation
English	hello	world
Spanish	hola	mundo
French	bonjour	monde
German	hallo	Welt
Italian	ciao	mondo
Portuguese	olá	mundo
Japanese	こんにちは	世界
Korean	안녕하세요	세계
Chinese	你好	世界
Russian	привет	мир
Arabic	مرحبا	عالم
Hindi	नमस्ते	दुनिया
Dutch	hallo	wereld
Swedish	hej	värld
Greek	γεια	κόσμος

For a deeper dive into how this tool works:

• docs/langchain-polyglot-tool.md - LangChain basics
• docs/structured-output.md - Structured output with Zod validation

Learning More

The src/index.ts file is heavily documented with explanations of each piece. Start there to understand the code.

For the full MCP specification: https://modelcontextprotocol.io/