How do I use My MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@My MCP Server What's 15 plus 27?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

My MCP Server

A custom Model Context Protocol (MCP) server with an extensible tool architecture for Claude Code. This server makes it easy to add custom tools that Claude can use during conversations.

Features

Extensible Architecture: Easy-to-use pattern for adding new tools
TypeScript: Full type safety with TypeScript
Example Tools Included: Calculator and Echo tools to demonstrate the pattern
Production-Ready: Proper error handling and validation with Zod
Well-Documented: Clear examples and documentation for adding new tools

Available Tools

1. Calculate

Perform basic arithmetic operations (add, subtract, multiply, divide).

Example usage:

"Calculate 15 + 27"
"What's 100 divided by 4?"
"Multiply 8 by 9"

2. Echo

Echo a message back, with optional text transformation (uppercase/lowercase).

Example usage:

"Echo 'Hello World'"
"Echo 'test message' in uppercase"
"Echo 'LOUD TEXT' in lowercase"

Installation

1. Install Dependencies

npm install

2. Build the Project

npm run build

This will compile the TypeScript code to JavaScript in the build/ directory.

3. Configure Claude Code

Add the following configuration to your ~/.claude.json file:

{
  "mcpServers": {
    "my-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/martin/src/my-mcp/build/index.js"]
    }
  }
}

Important: Make sure to use the absolute path to your build/index.js file.

4. Restart Claude Code

After updating the configuration, restart Claude Code to load the MCP server.

Adding New Tools

Adding a new tool is simple and follows a consistent pattern:

Step 1: Create a New Tool File

Create a new file in src/tools/ with the naming convention your-tool.tool.ts:

import { z } from "zod";
import type { ToolDefinition } from "../types/index.js";

export const yourTool: ToolDefinition = {
  name: "your_tool_name",
  description: "Description of what your tool does",

  inputSchema: z.object({
    param1: z.string().describe("Description of parameter 1"),
    param2: z.number().optional().describe("Optional parameter 2"),
  }),

  handler: async (args) => {
    // Your tool logic here
    const result = `Processed: ${args.param1}`;

    return {
      content: [{
        type: "text",
        text: result
      }]
    };
  }
};

Step 2: Register the Tool

Add your tool to the registry in src/tools/index.ts:

import { yourTool } from "./your-tool.tool.js";

export const tools: ToolDefinition[] = [
  echoTool,
  calculatorTool,
  yourTool,  // Add your tool here
];

Step 3: Rebuild

npm run build

Step 4: Restart Claude Code

Restart Claude Code to load the new tool.

Step 5: Test

Try using your new tool in a conversation with Claude!

Tool Examples

Simple Text Processing Tool

import { z } from "zod";
import type { ToolDefinition } from "../types/index.js";

export const reverseTool: ToolDefinition = {
  name: "reverse",
  description: "Reverse a string",

  inputSchema: z.object({
    text: z.string().describe("The text to reverse"),
  }),

  handler: async (args) => {
    const reversed = args.text.split("").reverse().join("");

    return {
      content: [{
        type: "text",
        text: reversed
      }]
    };
  }
};

API Call Tool

import { z } from "zod";
import type { ToolDefinition } from "../types/index.js";

export const weatherTool: ToolDefinition = {
  name: "get_weather",
  description: "Get current weather for a location",

  inputSchema: z.object({
    location: z.string().describe("City name or zip code"),
  }),

  handler: async (args) => {
    try {
      // Make API call (example)
      const response = await fetch(
        `https://api.weather.example.com/current?location=${args.location}`
      );
      const data = await response.json();

      return {
        content: [{
          type: "text",
          text: `Weather in ${args.location}: ${data.temperature}°F, ${data.conditions}`
        }]
      };
    } catch (error) {
      return {
        isError: true,
        content: [{
          type: "text",
          text: `Failed to fetch weather: ${error instanceof Error ? error.message : 'Unknown error'}`
        }]
      };
    }
  }
};

Project Structure

my-mcp/
├── src/
│   ├── index.ts                    # Main entry point
│   ├── server.ts                   # Server initialization and request handlers
│   ├── tools/
│   │   ├── index.ts                # Tool registry (add new tools here)
│   │   ├── calculator.tool.ts      # Calculator tool implementation
│   │   └── echo.tool.ts            # Echo tool implementation
│   └── types/
│       └── index.ts                # TypeScript type definitions
├── build/                          # Compiled JavaScript (generated)
├── package.json                    # Project dependencies and scripts
├── tsconfig.json                   # TypeScript configuration
├── .gitignore                      # Git ignore rules
├── .env.example                    # Environment variable template
└── README.md                       # This file

Development

Build the Project

npm run build

Run in Development Mode

npm run dev

This will build and run the server, showing any startup logs.

Error Handling

All tools should handle errors gracefully and return structured error responses:

// Success response
return {
  content: [{
    type: "text",
    text: "Operation successful"
  }]
};

// Error response
return {
  isError: true,
  content: [{
    type: "text",
    text: "Error: Something went wrong"
  }]
};

Important Notes

Logging: Always use console.error() for logging, never console.log(). The latter corrupts JSON-RPC messages over stdio.
Input Validation: All inputs are automatically validated using Zod schemas
Error Messages: Provide clear, helpful error messages for debugging
Async Handlers: All tool handlers are async functions

Troubleshooting

Server Not Appearing in Claude Code

Check that the path in ~/.claude.json is absolute and correct
Verify the build succeeded: npm run build
Restart Claude Code completely
Check for errors: node build/index.js (should start without errors)

Tool Not Working

Verify the tool is added to the registry in src/tools/index.ts
Rebuild the project: npm run build
Restart Claude Code
Check the Zod schema matches your expected input format

TypeScript Errors

Make sure all imports use .js extensions (required for ES modules)
Run npm run build to see detailed error messages
Check that types are correctly imported from ../types/index.js

License

MIT

Contributing

Feel free to add more tools and share them! The modular architecture makes it easy to create and share tool implementations.

My MCP Server

My MCP Server

Features

Available Tools

1. Calculate

2. Echo

Installation

1. Install Dependencies

2. Build the Project

3. Configure Claude Code

4. Restart Claude Code

Adding New Tools

Step 1: Create a New Tool File

Step 2: Register the Tool

Step 3: Rebuild

Step 4: Restart Claude Code

Step 5: Test

Tool Examples

Simple Text Processing Tool

API Call Tool

Project Structure

Development

Build the Project

Run in Development Mode

Error Handling

Important Notes

Troubleshooting

Server Not Appearing in Claude Code

Tool Not Working

TypeScript Errors

License

Contributing

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API