Example MCP Server

A complete Model Context Protocol (MCP) server implementation in Node.js + TypeScript that integrates with Claude Desktop as a local tool.

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that enables large language models (like Claude) to safely interact with external tools and data sources. MCP servers expose capabilities (tools) that Claude can discover and invoke in real-time during conversations.

Key Features of MCP:

• Tool Discovery: Claude can query available tools and their parameters
• Safe Execution: Structured JSON-RPC messages with validation
• Stdio Transport: For local integration with Claude Desktop
• Extensible: Easy to add new tools with standardized interfaces

Project Structure

example-mcp-server/
├── src/
│   ├── mcp/
│   │   └── server.ts          # MCP server with stdio transport
│   ├── tools/
│   │   ├── index.ts           # Tool registry & dispatcher
│   │   ├── ping.ts            # Ping tool (health check)
│   │   └── system_info.ts     # System info tool
│   └── types/
│       └── index.ts           # Type definitions
├── package.json               # Dependencies & scripts
├── tsconfig.json              # TypeScript config
├── mcp.json                   # Claude Desktop manifest
└── README.md                  # This file

Getting Started

Prerequisites

• Node.js 18+ (LTS)
• npm or yarn
• Claude Desktop (for testing)

Installation

1. Clone or navigate to the project directory:

cd example-mcp-server

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

This compiles all .ts files in src/ to JavaScript in the dist/ folder.

Running the MCP Server

npm start

The server will start listening on stdin/stdout, ready to receive JSON-RPC messages.

Testing the Server Locally

Using curl with echo (Windows PowerShell)

Test the tools/list endpoint:

$message = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/list"
} | ConvertTo-Json -Compress
"$message" | node dist/mcp/server.js

Using a Node.js test script

Create test.js:

import { spawn } from "child_process";

const server = spawn("node", ["dist/mcp/server.js"]);

let output = "";

server.stdout.on("data", (data) => {
  const line = data.toString().trim();
  if (line) {
    console.log("Response:", JSON.parse(line));
    server.kill();
  }
});

server.on("close", () => {
  console.log("Server closed");
});

// Send initialize request
const initMsg = {
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "test-client", version: "1.0.0" },
  },
};

server.stdin.write(JSON.stringify(initMsg) + "\n");

// Wait a moment, then send tools/list
setTimeout(() => {
  const listMsg = { jsonrpc: "2.0", id: 2, method: "tools/list" };
  server.stdin.write(JSON.stringify(listMsg) + "\n");
}, 100);

Run with:

npm run build && node test.js

Available Tools

1. ping

A simple health check tool.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "output": "pong"
  }
}

2. system_info

Returns system and platform information.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "system_info",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "output": {
      "platform": "win32",
      "arch": "x64",
      "nodeVersion": "v20.10.0",
      "osType": "Windows_NT",
      "osRelease": "10.0.22621",
      "totalMemory": "16384 MB",
      "freeMemory": "8192 MB",
      "cpuCount": 8,
      "uptime": "24 hours"
    }
  }
}

Registering with Claude Desktop

To make this MCP server available in Claude Desktop:

Windows

1. Open %APPDATA%\Claude\claude_desktop_config.json
2. Add this server configuration:

{
  "mcpServers": {
    "example-mcp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\example-mcp-server\\dist\\mcp\\server.js"]
    }
  }
}

Replace C:\path\to\example-mcp-server with the actual full path to your project.

macOS

1. Open ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the server configuration (use POSIX paths)

Linux

1. Open ~/.config/Claude/claude_desktop_config.json
2. Add the server configuration

Example Configuration

{
  "mcpServers": {
    "example-mcp-server": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\projects\\example-mcp-server\\dist\\mcp\\server.js"]
    }
  }
}

3. Restart Claude Desktop for the changes to take effect
4. In Claude, look for the tool icon or mention "use the ping tool" or "check system info"

Adding New Tools

To add a new tool:

1. Create a tool file in src/tools/ (e.g., src/tools/my_tool.ts):

import { ToolHandler } from "../types/index.js";

export const myToolHandler: ToolHandler = async (args) => {
  // Implement your tool logic
  return { result: "Your result here" };
};

export const myToolDefinition = {
  name: "my_tool",
  description: "Description of what your tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "First parameter" },
      param2: { type: "number", description: "Second parameter" },
    },
    required: ["param1"],
  },
};

2. Register it in src/tools/index.ts:

import { myToolHandler, myToolDefinition } from "./my_tool.js";

const registry: ToolRegistry = {
  // ... existing tools
  my_tool: {
    definition: myToolDefinition,
    handler: myToolHandler,
  },
};

3. Rebuild and restart:

npm run build
npm start

MCP Protocol Overview

The server implements the MCP specification with support for:

• initialize: Handshake with client
• tools/list: Returns available tools and schemas
• tools/call: Executes a tool with provided arguments

All communication uses JSON-RPC 2.0 format with structured error handling.

Troubleshooting

Server won't start

• Ensure Node.js 18+ is installed: node --version
• Check TypeScript compiled correctly: npm run build
• Verify dist/mcp/server.js exists

Claude Desktop doesn't see the server

• Double-check the path in claude_desktop_config.json is correct and absolute
• Restart Claude Desktop after updating config
• Check server runs locally: npm start

Tool calls fail

• Ensure tool name matches exactly (case-sensitive)
• Verify required parameters are provided
• Check error message in JSON-RPC response

Scripts

npm run build    # Compile TypeScript to dist/
npm start        # Run the MCP server
npm run dev      # Build and run in one command

License

MIT

References

• Model Context Protocol Documentation
• Claude Desktop Integration
• JSON-RPC 2.0 Specification