Skip to content
protomcp

Quick Start

  1. Install protomcp

    Terminal window
    brew install msilverblatt/tap/protomcp

  2. Install the SDK

    Terminal window
    # Python
    pip install protomcp
    

    # TypeScript
    npm install protomcp zod
    

    # Go
    go get github.com/msilverblatt/protomcp/sdk/go
    

    # Rust
    cargo add protomcp serde_json
    cargo add tokio --features full

  3. Write a tool file

    Create tools.py (Python):

    from protomcp import tool, ToolResult
    

    @tool("Add two numbers together")
    def add(a: int, b: int) -> ToolResult:
        return ToolResult(result=str(a + b))
    

    @tool("Greet a user by name")
    def greet(name: str) -> ToolResult:
        return ToolResult(result=f"Hello, {name}!")

    Or create tools.ts (TypeScript):

    import { tool, ToolResult } from 'protomcp';
    import { z } from 'zod';
    

    tool({
      description: 'Add two numbers together',
      args: z.object({ a: z.number(), b: z.number() }),
      handler: function add({ a, b }) {
        return new ToolResult({ result: String(a + b) });
      },
    });
    

    tool({
      description: 'Greet a user by name',
      args: z.object({ name: z.string() }),
      handler: function greet({ name }) {
        return new ToolResult({ result: `Hello, ${name}!` });
      },
    });

  4. Run in dev mode

    Terminal window
    # Python
    pmcp dev tools.py
    

    # TypeScript
    pmcp dev tools.ts

    You should see:

    [protomcp] listening on stdio
    [protomcp] loaded 2 tools: add, greet

  5. Configure your MCP client

    Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

    {
      "mcpServers": {
        "mytools": {
          "command": "pmcp",
          "args": ["dev", "/absolute/path/to/tools.py"]
        }
      }
    }

    Use the full path to your tool file (.py or .ts). Restart your MCP client. The tools add and greet will appear.

  6. Try hot reload

    While the MCP client is running, add a new tool to your file:

    # Python
    @tool("Reverse a string")
    def reverse(text: str) -> ToolResult:
        return ToolResult(result=text[::-1])
    // TypeScript
    tool({
      description: 'Reverse a string',
      args: z.object({ text: z.string() }),
      handler: function reverse({ text }) {
        return new ToolResult({ result: text.split('').reverse().join('') });
      },
    });

    Save the file. protomcp reloads automatically — no restart needed. The new tool appears in your client within seconds.

Next steps