test-dh-mcp

test-dh-mcp

This project demonstrates how to define and run an MCP (Multi-Channel Protocol) server using the FastMCP implementation. It includes examples for tool registration, server/client usage, and integration with Claude Desktop and MCP Inspector.

• MCP Server Quickstart
• mcp Python package documentation (PyPI)

Project Structure

• src/mcp_server.py — Main entrypoint to run the MCP server (configurable for SSE or stdio transport).
• src/dhmcp/__init__.py — All tools are registered here using the @mcp_server.tool() decorator.
• src/mcp_client.py — Example async client for testing tools.
• requirements.txt — Python dependencies (including mcp[cli] and autogen-ext).

Using uv for Dependency Management

uv is a modern, ultra-fast Python package manager and runner. It can be used as a drop-in replacement for pip and venv, providing faster installs and improved dependency management.

Key Concepts

• pyproject.toml: The modern, recommended way to specify your project's dependencies and metadata. uv uses this as the source of truth.
• requirements.txt: Supported for compatibility with traditional Python tools and workflows. Optional if you use pyproject.toml.
• uv.lock: Lockfile for reproducible installs (auto-managed by uv).

Modern Workflow (Recommended)

1. Add dependencies directly to your project:

   uv pip install <package>
   # Example:
   uv pip install autogen-ext mcp[cli]
   

   This updates pyproject.toml and uv.lock.
2. Sync environment:

   uv pip install  # Installs all dependencies from pyproject.toml
   

3. Run scripts:

   uv run src/mcp_server.py
   uv run src/mcp_client.py
   

4. Upgrade dependencies:

   uv sync --upgrade
   

Compatibility Workflow (requirements.txt)

• If you have an existing requirements.txt, you can use:

  uv pip install -r requirements.txt
  # or
  uv add --requirements requirements.txt
  

• This will sync dependencies and update your lockfile. You can keep both files in sync for maximum compatibility.

Notes

• requirements.txt is optional with uv. For new projects, you can rely entirely on pyproject.toml and uv.lock.
• For legacy projects or sharing with users of pip, keep requirements.txt up to date.
• uv works with or without a virtual environment. Use uv venv .venv to create one if desired.
• If you have multiple environments, use --active to target the currently activated one.

Quick Start: Server

1. Install dependencies

It is recommended to use a virtual environment:

• Using venv:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• Using uv:

uv pip install -r requirements.txt

2. Run the MCP Server

From the project root, run (choose the transport that fits your use case):

• SSE transport (default, for browser/web clients):

  python src/mcp_server.py
  # or, explicitly:
  python src/mcp_server.py --transport sse
  # or, using uv:
  uv run src/mcp_server.py
  

  The server will listen on http://localhost:8000/sse

• Stdio transport (recommended for Claude Desktop/Inspector):

  python src/mcp_server.py --transport stdio
  # or, using uv:
  uv run src/mcp_server.py --transport stdio
  

  The server will communicate via stdio (no HTTP port needed).

You should see log output indicating the server is running with the selected transport.

Quick Start: Client

Note: The Python client (mcp_client.py) requires the MCP server to be running in SSE mode (the default). It will not work if the server is running in stdio mode.

1. Install dependencies

It is recommended to use a virtual environment:

• Using venv:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• Using uv:

uv pip install -r requirements.txt

2. Run the MCP Client

From the project root, run:

• Using venv:

cd src
python -m mcp_client

• Using uv:

cd src
uv run mcp_client.py

You should see log output indicating the client is running and listing available tools.

Claude Desktop

You can connect Claude Desktop to your local stdio MCP server to use custom tools.

1. Edit ~/Library/Application\ Support/Claude/claude_desktop_config.json to add your MCP server. Deephaven worker configuration is now handled entirely via a JSON config file, and the path must be specified using the required DH_MCP_CONFIG_FILE environment variable. There is no default path—this environment variable must always be set.

   Example Claude Desktop config (using venv):

   {
     "mcpServers": {
       "test-dh-mcp": {
         "command": "/Users/chip/dev/test-dh-mcp/.venv/bin/python3",
         "args": ["/Users/chip/dev/test-dh-mcp/src/mcp_server.py", "--transport", "stdio"],
         "env": {
           "DH_MCP_CONFIG_FILE": "/Users/chip/dev/test-dh-mcp/deephaven_workers.json"
         }
       }
     }
   }
   

   Or with uv:

   {
     "mcpServers": {
       "test-dh-mcp": {
         "command": "uv",
         "args": [
           "--directory",
           "/Users/chip/dev/test-dh-mcp/src",
           "run",
           "mcp_server.py",
           "--transport",
           "stdio"
         ],
         "env": {
           "DH_MCP_CONFIG_FILE": "/Users/chip/dev/test-dh-mcp/deephaven_workers.json"
         }
       }
     }
   }
   

   Note: Always set DH_MCP_CONFIG_FILE in the env section if your config is not named deephaven_workers.json in the project root, or if you want to be explicit about the config location.

      "args": [
        "--directory",
        "/Users/chip/dev/test-dh-mcp/src",
        "run", 
        "mcp_server.py", 
        "--transport", 
        "stdio"
      ],
      "env": {
        "DH_MCP_SERVER_NAME": "test-dh-mcp",
        "DH_MCP_HOST": "localhost",
        "DH_MCP_PORT": "10000",
        "DH_MCP_AUTH_TYPE": "Anonymous"
      }
    }
   

   } }

Note: All DH_MCP_* environment variables listed in the Deephaven Session Configuration section can be set here. These control the Deephaven session for every tool call.

4. Restart Claude Desktop.
5. Debugging logs can be found in ~/Library/Logs/Claude/

Deephaven Worker Configuration

All Deephaven worker configuration is now handled via a JSON file. The path to this file must be specified using the DH_MCP_CONFIG_FILE environment variable. There is no default path—this variable is required.

The config file should look like this:

{
  "workers": {
    "worker1": {
      "host": "localhost",
      "port": 10000,
      "auth_type": "Anonymous",
      "auth_token": "",
      "never_timeout": true
    },
    "worker2": {
      "host": "otherhost",
      "port": 10001,
      "auth_type": "Bearer",
      "auth_token": "YOUR_TOKEN"
    }
  },
  "default_worker": "worker1"
}

• The workers object maps worker names to their connection settings.
• The default_worker is optional and used if a worker name is not specified in a tool call. If set, it must match one of the keys in the workers dictionary.

Important: The DH_MCP_CONFIG_FILE environment variable must always be set to the path of your worker config file. There is no default config path.

Supported fields for each worker:

Note: You may define workers with only a subset of these fields, depending on your use case and authentication method. No fields are strictly required; defaults will be used where possible.

Tool Usage

• echo_tool(message: str) -> str: Echoes back the input message, prefixed with 'Echo:'.
• gnome_count_colorado() -> int: Returns the current number of gnomes in Colorado (demo tool).
• deephaven_worker_names() -> list[str]: Returns all configured Deephaven worker names from the config file.
• deephaven_default_worker() -> str: Returns the name of the default worker as set in config (or None if not set).
• deephaven_list_tables(worker_name: str = None) -> list: Lists table names for the specified worker. If worker_name is not provided, uses the default_worker from config.
• deephaven_table_schemas(worker_name: str = None) -> list: Returns schemas for all tables in the specified worker. If worker_name is not provided, uses the default_worker from config.

See the example config file above for how to set up multiple workers.

Registering Tools

Define new tools in dhmcp/__init__.py using the @mcp_server.tool() decorator. Example:

@mcp_server.tool()
def echo_tool(message: str) -> str:
    """
    Echo tool that returns the input message prefixed with 'Echo:'.
    """
    return f"Echo: {message}"

Troubleshooting

• Ensure you are running commands from the correct directory (src for direct script execution).
• If you change tool definitions, restart the server.
• For connection issues, check that the server is running and listening on the expected address/port (for SSE), or correctly attached via stdio (for Claude/Inspector).

Is the server running?

• SSE mode:

  curl http://localhost:8000/sse
  

• Stdio mode:
  • Check your Claude/Inspector logs for successful connection and tool listing.

MCP Inspector

The MCP Inspector is a tool that allows you to inspect the state of an MCP server.

1. Install the MCP Inspector:

   npm install -g @modelcontextprotocol/inspector@latest
   

2. Run the MCP Inspector:

⚠️ WARNING: When using the MCP Inspector, all string values must be entered with quotes (e.g., "worker1"). If you do not use quotes, the Inspector may send null or invalid values to the server. The value can be validated by clicking on the Format JSON button.

- ** SSE mode: **

    - Using `venv`:

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    /Users/chip/dev/test-dh-mcp/venv/bin/python3 mcp_server.py --transport sse
    ```

    - Using `uv`:

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    uv run mcp_server.py --transport sse
    ```

- ** Stdio mode: **

    - Using `venv`:

    ```
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    /Users/chip/dev/test-dh-mcp/venv/bin/python3 mcp_server.py --transport stdio
    ```

    - Using `uv`:

    ```bash
    cd /Users/chip/dev/test-dh-mcp/src
    npx @modelcontextprotocol/inspector@latest \
    uv run mcp_server.py --transport stdio
    ```