### Install Multi-MCP with uv

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Clone the repository and install dependencies using uv. This is the recommended installation method.

```bash
git clone https://github.com/kfirtoledo/multi-mcp.git
cd multi-mcp

uv venv
uv pip install -r requirements.txt
```

--------------------------------

### Install Project Dependencies with UV

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Sets up a virtual environment and installs project dependencies using the 'uv' package manager.

```bash
uv venv
uv pip install -r requirements.txt
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Illustrates the JSON structure for configuring backend MCP servers, including command-line execution and HTTP URLs.

```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["./tools/get_weather.py"],
      "env": {"API_KEY": "value"}
    },
    "remote_service": {
      "url": "http://127.0.0.1:9080/sse"
    }
  }
}
```

--------------------------------

### Example Tested Tools

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

These are examples of how MCP tools are namespaced and accessed through the multi-mcp proxy. Ensure these patterns are followed when interacting with configured MCP servers.

```text
mcp__multi-mcp__github_search_repositories
```

```text
mcp__multi-mcp__brave-search_brave_web_search
```

```text
mcp__multi-mcp__context7_resolve-library-id
```

```text
mcp__multi-mcp__context7_get-library-docs
```

--------------------------------

### Environment Variables and Start Command

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Sets project-specific environment variables and then starts the Multi-MCP application using uv. Ensure the MULTI_MCP_PORT variable matches the desired port.

```bash
# Project-specific configuration
export PROJECT_ID="my-awesome-project"
export MEMORY_PATH="./memory/${PROJECT_ID}-knowledge.jsonl"
export MULTI_MCP_PORT="8080"

# Start multi-mcp with project context
uv run main.py --transport sse --host 0.0.0.0 --port ${MULTI_MCP_PORT}
```

--------------------------------

### MCPProxyServer API Example (Python)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Illustrates how to create and manage an MCPProxyServer, which aggregates capabilities from multiple MCP servers. Shows registering and unregistering clients at runtime.

```python
from src.multimcp.mcp_proxy import MCPProxyServer
from src.multimcp.mcp_client import MCPClientManager

async def example():
    # Create client manager and connect to servers
    manager = MCPClientManager()
    await manager.create_clients(config)

    # Create proxy server (factory method)
    proxy = await MCPProxyServer.create(manager)

    # Register a new client at runtime
    new_client = await manager.create_clients({
        "mcpServers": {
            "new_server": {"command": "python", "args": ["./new_tool.py"]}
        }
    })
    await proxy.register_client("new_server", new_client["new_server"])

    # Unregister a client
    await proxy.unregister_client("new_server")
```

--------------------------------

### Direct Run with UV (Automatic Dependency Handling)

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Runs the main application script using 'uv', which automatically handles dependency installation.

```bash
uv run main.py
```

--------------------------------

### Install and Run Multi-MCP on VPS

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Commands to install and run Multi-MCP on a Virtual Private Server using `uv` and configure Claude Code to connect remotely.

```bash
# Install and run multi-mcp on VPS
uv run main.py --transport sse --host 0.0.0.0 --port 8080

# Configure Claude Code locally to connect remotely
claude mcp add --transport sse multi-mcp https://your-vps-ip:8080/sse
```

--------------------------------

### Tool Namespacing Implementation Example

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Demonstrates the internal logic for namespacing tools in `MCPProxyServer` using `_make_key` and `_split_key` methods to prevent naming conflicts.

```python
# _make_key(server_name, tool_name) creates `server_name_tool_name` identifiers
# _split_key(key) splits namespaced keys back into `(server, tool)` tuples using first underscore
```

--------------------------------

### Docker Volume Mounting for Multi-MCP Persistence

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Demonstrates Docker volume mounting for persistent memory and configuration files, based on setup guide recommendations.

```bash
# From setup guide pattern
docker run -d -p 8080:8080 \
  --name multi-mcp-with-knowledge \
  -v $(pwd)/knowledge-memory:/app/memory \
  -v $(pwd)/config-with-knowledge.json:/app/mcp.json \
  multi-mcp:latest --transport sse --host 0.0.0.0
```

--------------------------------

### Multi-MCP Configuration File

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Example JSON configuration file for Multi-MCP, specifying the knowledge graph server details including its command and arguments.

```json
{
  "mcpServers": {
    "knowledge-graph": {
      "command": "npx",
      "args": [
        "-y", 
        "@shaneholloman/mcp-knowledge-graph",
        "--memory-path",
        "./memory/multi-mcp-knowledge.jsonl"
      ]
    }
  }
}
```

--------------------------------

### Start Multi-MCP in SSE Mode

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Use this command to start the Multi-MCP server in Server-Sent Events (SSE) mode. Ensure you are in the 'multi-mcp' directory.

```bash
cd multi-mcp
uv run main.py --transport sse --host 0.0.0.0 --port 8080
```

--------------------------------

### Docker Compose Example for Multi-MCP with Knowledge

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

A Docker Compose configuration for running Multi-MCP with persistent knowledge graph memory and a read-only configuration file.

```yaml
version: '3.8'
services:
  multi-mcp-with-knowledge:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./memory:/app/memory:rw
      - ./config-with-knowledge.json:/app/mcp.json:ro
    environment:
      - KNOWLEDGE_GRAPH_MEMORY_PATH=/app/memory/knowledge-graph.jsonl
    restart: unless-stopped
```

--------------------------------

### Configure Initial MCP Servers (STDIO)

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Define the initial MCP-compatible servers to spawn and connect at startup using a JSON configuration file. This example shows two servers, 'weather' and 'calculator', both running Python scripts.

```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["./tools/get_weather.py"]
    },
    "calculator": {
      "command": "python",
      "args": ["./tools/calculator.py"]
    }
  }
}
```

--------------------------------

### Configure Initial MCP Servers (SSE)

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Connect to a remote MCP server using SSE by specifying its URL in the JSON configuration. This example connects to a 'weather' server at a local address.

```json
{
  "mcpServers": {
    "weather": {
      "url": "http://127.0.0.1:9080/sse"
    }
  }
}
```

--------------------------------

### MCPClientManager API Example (Python)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Demonstrates the usage of MCPClientManager for creating, retrieving, and cleaning up MCP client sessions based on a configuration dictionary. Supports both command execution and SSE transport.

```python
from src.multimcp.mcp_client import MCPClientManager

async def example():
    manager = MCPClientManager()

    # Create clients from configuration
    config = {
        "mcpServers": {
            "calculator": {
                "command": "python",
                "args": ["./tools/calculator.py"]
            },
            "weather": {
                "url": "http://localhost:9080/sse"
            }
        }
    }

    clients = await manager.create_clients(config)
    # Returns: {"calculator": ClientSession, "weather": ClientSession}

    # Get a specific client
    calc_client = manager.get_client("calculator")

    # Clean up all clients
    await manager.close()
```

--------------------------------

### List Available Tools (GET /mcp_tools)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Retrieve a list of all available tools, grouped by their source MCP server. This endpoint shows the tool names exposed by each connected server.

```bash
curl -X GET http://localhost:8080/mcp_tools

# Response:
# {
#   "tools": {
#     "weather": ["get_weather"],
#     "calculator": ["add", "multiply"]
#   }
# }
```

--------------------------------

### Run Multi-MCP Server with Custom Configuration

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

This command launches the Multi-MCP server using a specified JSON configuration file, allowing for custom backend server setups.

```bash
uv run main.py --config ./examples/config/mcp_k8s.json
```

--------------------------------

### Run Multi-MCP Server in SSE Mode

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Execute this command to start the Multi-MCP server with the SSE (Server-Sent Events) transport, specifying custom host and port for network-based communication.

```bash
uv run main.py --transport sse --host 0.0.0.0 --port 8080
```

--------------------------------

### Create MCP Tool Server with FastMCP

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Example of creating a backend MCP tool server using FastMCP. This server can be connected to the Multi-MCP proxy. Defines tools like 'add' and 'multiply'.

```python
# calculator.py - Math operations server
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Calculator")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multiply two numbers"""
    return a * b

if __name__ == "__main__":
    mcp.run()
```

--------------------------------

### Add Project-Specific Knowledge Graph Server via API

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This example demonstrates how to dynamically add a project-specific knowledge graph server to multi-mcp using its SSE API. It specifies the command, arguments, and a unique memory path for the project.

```bash
# Add project-specific knowledge graph server
curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge-graph-project-a": {
      "command": "npx",
      "args": ["-y", "@shaneholloman/mcp-knowledge-graph", "--memory-path", "./memory/project-a.jsonl"]
    }
  }'
```

--------------------------------

### Connect to Multi-MCP from LangGraph Client

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Example environment variables required for connecting an MCP-compatible client, such as LangGraph, to the Multi-MCP proxy. Ensure your model name, base URL, and API key are set.

```env
MODEL_NAME=<your-model-name>
BASE_URL=<https://your-openai-base-url>
OPENAI_API_KEY=<your-api-key>
```

--------------------------------

### GET /mcp_servers - List Active Servers

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Retrieves a list of all currently connected MCP servers by their registered names.

```APIDOC
## GET /mcp_servers - List Active Servers

### Description
Returns a list of all currently connected MCP servers by name.

### Method
GET

### Endpoint
/mcp_servers

### Response
#### Success Response (200)
- **active_servers** (array) - A list of strings, where each string is the name of an active MCP server.

### Response Example
```json
{
  "active_servers": ["weather", "calculator"]
}
```
```

--------------------------------

### GET /mcp_tools - List Available Tools

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Retrieves a comprehensive list of all available tools, organized by the MCP server they belong to. This provides an overview of the tools exposed by each connected server.

```APIDOC
## GET /mcp_tools - List Available Tools

### Description
Returns all available tools grouped by their source server, showing the tool names exposed by each connected MCP server.

### Method
GET

### Endpoint
/mcp_tools

### Response
#### Success Response (200)
- **tools** (object) - An object where keys are server names and values are arrays of tool names available on that server.

### Response Example
```json
{
  "tools": {
    "weather": ["get_weather"],
    "calculator": ["add", "multiply"]
  }
}
```
```

--------------------------------

### Add Server JSON Configuration

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

JSON payload for adding a new MCP server. This example defines a 'unit_converter' server that runs a Python script.

```json
{
  "mcpServers": {
    "unit_converter": {
      "command": "python",
      "args": ["./tools/unit_converter.py"]
    }
  }
}
```

--------------------------------

### LangGraph Agent Integration with Multi-MCP Client (Python)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Connects a LangGraph agent to the Multi-MCP proxy to access aggregated tools. This example demonstrates connecting via STDIO and using the weather and calculator tools.

```python
import os
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv

load_dotenv()

model = ChatOpenAI(
    model=os.environ.get("MODEL_NAME"),
    base_url=os.environ["BASE_URL"],
    api_key=os.environ["OPENAI_API_KEY"],
    temperature=0.7,
)

async def main():
    async with MultiServerMCPClient() as client:
        # Connect via STDIO
        await client.connect_to_server(
            "multi-mcp",
            command="python",
            args=["./main.py"],
        )

        # Or connect via SSE
        # await client.connect_to_server(
        #     "multi-mcp",
        #     transport="sse",
        #     url="http://127.0.0.1:8080/sse",
        # )

        # Get aggregated tools from all connected MCP servers
        tools = client.get_tools()
        print(f"Available tools: {[tool.name for tool in tools]}")
        # Output: ['calculator_add', 'calculator_multiply', 'weather_get_weather']

        # Create agent with MCP tools
        agent = create_react_agent(model, tools)

        # Use weather tool
        response = await agent.ainvoke({"messages": "What is the weather in London?"})
        for m in response['messages']:
            m.pretty_print()

        # Use calculator tool
        response = await agent.ainvoke({"messages": "What's 10 + 5?"})
        for m in response['messages']:
            m.pretty_print()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### List Active MCP Servers (GET /mcp_servers)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Retrieve a list of all currently connected MCP servers by their registered names. Requires an active SSE connection to the proxy.

```bash
curl -X GET http://localhost:8080/mcp_servers

# Response:
# {"active_servers": ["weather", "calculator"]}
```

--------------------------------

### Docker Commands for Multi-Instance Isolation

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Example Docker commands for running isolated instances of Multi-MCP for different projects (Project A and Project B). Each instance uses separate memory and configuration volumes and sets a unique PROJECT_ID environment variable.

```bash
# Project A instance
docker run -d -p 8080:8080 \
  --name multi-mcp-project-a \
  -v ./project-a-memory:/app/memory \
  -v ./project-a-config.json:/app/mcp.json \
  -e PROJECT_ID=project-a \
  multi-mcp:latest --transport sse --host 0.0.0.0

# Project B instance  
docker run -d -p 8081:8080 \
  --name multi-mcp-project-b \
  -v ./project-b-memory:/app/memory \
  -v ./project-b-config.json:/app/mcp.json \
  -e PROJECT_ID=project-b \
  multi-mcp:latest --transport sse --host 0.0.0.0
```

--------------------------------

### Enhance Dockerfile for Knowledge Graph Persistence

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This Dockerfile snippet shows how to add a directory for knowledge graph memory and configure a volume for persistence. It assumes a base multi-mcp Dockerfile and installs Node.js if not already present.

```dockerfile
# Building on existing multi-mcp Dockerfile
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim

# Copy existing multi-mcp setup
COPY . /app
WORKDIR /app

# Add memory directory for knowledge graph
RUN mkdir -p /app/memory && chmod 755 /app/memory

# Volume for persistent memory
VOLUME ["/app/memory"]

# Install Node.js for knowledge graph server (if not already present)
RUN apt-get update && apt-get install -y nodejs npm && rm -rf /var/lib/apt/lists/*

```

--------------------------------

### GET /sse - SSE Connection Endpoint

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

The Server-Sent Events (SSE) endpoint used by MCP clients to establish a persistent, bidirectional communication channel with the Multi-MCP proxy server.

```APIDOC
## GET /sse - SSE Connection Endpoint

### Description
The Server-Sent Events endpoint for MCP clients to establish a persistent connection with the proxy server.

### Method
GET

### Endpoint
/sse

### Usage
Clients can connect to this endpoint using an MCP-compatible client to stream MCP protocol messages.

### Example Connection URL
`http://localhost:8080/sse`
```

--------------------------------

### SSE Connection Endpoint (GET /sse)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

The Server-Sent Events (SSE) endpoint for MCP clients to establish a persistent connection with the Multi-MCP proxy server. This streams MCP protocol messages.

```bash
# Connect using an MCP-compatible client
# The SSE endpoint streams MCP protocol messages

# Example connection URL for clients:
http://localhost:8080/sse
```

--------------------------------

### Verify Integration and Check Available Tools

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

After adding the knowledge graph server, use this command to check the available tools. The output should include tools related to the knowledge graph.

```bash
# Check available tools
curl http://localhost:8080/mcp_tools

# Should show knowledge graph tools with naming pattern:
# knowledge-graph_add_memory
# knowledge-graph_search_nodes
# knowledge-graph_read_graph
```

--------------------------------

### Quick Development Run

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

A shortcut command for quickly running the Multi-MCP server during development.

```bash
make run
```

--------------------------------

### Deploying Multi-MCP with Kind and Accessing SSE Endpoint

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Steps to deploy the multi-mcp application using Kind, load the Docker image, apply the Kubernetes configuration, and access the SSE endpoint. Replace '<kind-node-ip>' with the actual IP address of your Kind node.

```bash
# Deploy with Kind cluster
kind create cluster --name multi-mcp-test
kind load docker-image multi-mcp --name multi-mcp-test
kubectl apply -f examples/k8s/multi-mcp.yaml

# Access the SSE endpoint
curl http://<kind-node-ip>:30080/sse

```

--------------------------------

### Create Kind Kubernetes Cluster

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Initializes a local Kubernetes cluster using Kind with the specified name for testing.

```bash
kind create cluster --name multi-mcp-test
```

--------------------------------

### Docker Build and Run Commands

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Provides commands for building the Multi-MCP Docker image and running it as a container. Supports both 'make' targets and direct Docker commands.

```bash
# Build the Docker image
make docker-build
# Or manually:
docker build -t multi-mcp .

# Run the container with SSE transport
make docker-run
# Or manually:
docker run -p 8080:8080 multi-mcp
```

--------------------------------

### POST /mcp_servers - Add MCP Server at Runtime

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Dynamically adds a new MCP server to the proxy without requiring a server restart. The newly added server's tools become immediately available.

```APIDOC
## POST /mcp_servers - Add MCP Server at Runtime

### Description
Dynamically add a new MCP server to the proxy without restart. The server is immediately initialized and its tools become available.

### Method
POST

### Endpoint
/mcp_servers

### Parameters
#### Request Body
- **mcpServers** (object) - Required - An object where keys are the desired names for the new MCP servers and values are their configurations.
  - **server_name** (object) - Required - Configuration for a single MCP server.
    - **command** (string) - Optional - The command to execute for a STDIO-based server.
    - **args** (array) - Optional - Arguments to pass to the command for a STDIO-based server.
    - **env** (object) - Optional - Environment variables for the STDIO-based server process.
    - **url** (string) - Optional - The URL for an SSE-based server.

### Request Example
```json
{
  "mcpServers": {
    "unit_converter": {
      "command": "python",
      "args": ["./tools/unit_converter.py"]
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating which servers were added.

#### Response Example
```json
{
  "message": "Added ['unit_converter']"
}
```
```

--------------------------------

### Add MCP Server at Runtime (POST /mcp_servers)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Dynamically add a new MCP server to the proxy without requiring a restart. Supports both STDIO and SSE based servers. Tools from the new server become available immediately.

```bash
# Add a new STDIO-based server
curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  -d '{
    "mcpServers": {
      "unit_converter": {
        "command": "python",
        "args": ["./tools/unit_converter.py"]
      }
    }
  }'

# Response:
# {"message": "Added ['unit_converter']"}
```

```bash
# Add a remote SSE-based server
curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  -d '{
    "mcpServers": {
      "remote_tools": {
        "url": "http://remote-host:9080/sse"
      }
    }
  }'

# Response:
# {"message": "Added ['remote_tools']"}
```

--------------------------------

### Run MultiMCP Server in Python

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Initialize and run the MultiMCP server. Supports both STDIO (default) and SSE (HTTP) transport modes. Configure host, port, and log level as needed.

```python
import asyncio
from src.multimcp.multi_mcp import MultiMCP

# Initialize and run in STDIO mode (default)
server = MultiMCP(
    transport="stdio",
    config="./mcp.json",
    log_level="INFO"
)
asyncio.run(server.run())
```

```python
server = MultiMCP(
    transport="sse",
    config="./mcp.json",
    host="127.0.0.1",
    port=8080,
    log_level="INFO"
)
asyncio.run(server.run())
```

--------------------------------

### Manage Multi-MCP Servers at Runtime via API

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Demonstrates using `curl` to interact with the Multi-MCP API for dynamic server management, including adding, listing, and removing servers.

```bash
# Add servers at runtime via API
curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  -d @new-server-config.json

# List active servers
curl http://localhost:8080/mcp_servers

# Remove servers
curl -X DELETE http://localhost:8080/mcp_servers/server-name
```

--------------------------------

### Deploy Multi-MCP with Kind

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Deploy the Multi-MCP proxy to a local Kubernetes cluster using Kind. This involves creating a cluster, loading the Docker image, and applying the Kubernetes manifest.

```bash
kind create cluster --name multi-mcp-test
kind load docker-image multi-mcp --name multi-mcp-test
kubectl apply -f k8s/multi-mcp.yaml
```

--------------------------------

### Build Multi-MCP Docker Image

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Build the Docker image for the SSE server using the provided Makefile. This is a prerequisite for containerized deployment.

```bash
make docker-build
```

--------------------------------

### Run End-to-End Integration Tests

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

This command initiates the end-to-end integration tests for the Multi-MCP project.

```bash
make test-e2e
```

--------------------------------

### Run Client Lifecycle Management Tests

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Execute the tests focused on the client lifecycle management aspects of the Multi-MCP server.

```bash
make test-lifecycle
```

--------------------------------

### Run Multi-MCP Project B in Docker

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Launches a Docker container for Project B, mapping configuration and memory volumes, and specifying the transport and host.

```bash
docker run -d -p 8081:8080 \
  --name multi-mcp-project-b \
  -v $(pwd)/project-b-config:/app/mcp.json \
  -v $(pwd)/project-b-memory:/app/memory \
  multi-mcp:latest --transport sse --host 0.0.0.0
```

--------------------------------

### Enhanced Tool Routing for Project Context

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Python code for an MCPProxyServer class that includes enhanced tool routing based on project context. This is part of the development for multi-instance support.

```python
# Enhanced tool routing  
class MCPProxyServer:
    async def call_tool(self, name: str, arguments: dict, context: dict = None):
        project_id = context.get('project_id') if context else None
        # Route to appropriate project-specific server

```

--------------------------------

### Run All Multi-MCP Tests

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

A command to execute all available test suites for the Multi-MCP project.

```bash
make all-test
```

--------------------------------

### Configure MCP Servers with Environment Variables

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This JSON configuration shows how to define MCP servers, specifically the knowledge graph, using environment variables for dynamic path configuration. The `PROJECT_MEMORY_PATH` variable allows each project to have its own memory file.

```json
{
  "mcpServers": {
    "knowledge-graph": {
      "command": "npx",
      "args": ["-y", "@shaneholloman/mcp-knowledge-graph", "--memory-path", "${PROJECT_MEMORY_PATH}"]
    }
  }
}
```

--------------------------------

### Run Core Proxy Functionality Tests

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Execute this command to run the test suite specifically for the core proxy functionality of Multi-MCP.

```bash
make test-proxy
```

--------------------------------

### Enhanced API Endpoints for Project Context

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Python code demonstrating enhanced API endpoints for adding servers within a specific project context. This is part of the development required for multi-instance support.

```python
# Enhanced API endpoints
@app.route("/mcp_servers/project/{project_id}", methods=["POST"])
async def add_project_servers(request):
    """Add servers for specific project context"""

```

--------------------------------

### List Available Tools using cURL

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Retrieve a list of all available tools within the MCP system using this cURL command.

```bash
curl http://localhost:8080/mcp_tools
```

--------------------------------

### CLI Usage for MultiMCP Server

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Run the MultiMCP proxy server from the command line. Options include transport mode (stdio/sse), host, port, configuration file path, and log level.

```bash
# Run in STDIO mode (default)
uv run main.py --transport stdio
```

```bash
# Run in SSE mode with custom host and port
uv run main.py --transport sse --host 0.0.0.0 --port 8080
```

```bash
# Use custom configuration file
uv run main.py --transport sse --config ./examples/config/mcp.json
```

```bash
# Enable debug logging
uv run main.py --transport sse --log-level DEBUG
```

--------------------------------

### Docker Command for Multi-MCP with Knowledge Graph

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Docker command to run Multi-MCP with a knowledge graph server. It maps ports, mounts volumes for memory and configuration, and specifies transport and host settings.

```bash
docker run -d -p 8080:8080 \
  --name multi-mcp-knowledge \
  -v $(pwd)/memory:/app/memory:rw \
  -v $(pwd)/config-with-knowledge.json:/app/mcp.json:ro \
  multi-mcp:latest --transport sse --host 0.0.0.0
```

--------------------------------

### Run Kubernetes Deployment Tests

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

This command runs tests related to the Kubernetes deployment of Multi-MCP. It requires Docker to be built.

```bash
make test-k8s
```

--------------------------------

### Load Docker Image into Kind Cluster

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Loads the previously built Multi-MCP Docker image into the Kind Kubernetes cluster.

```bash
kind load docker-image multi-mcp --name multi-mcp-test
```

--------------------------------

### Run Multi-MCP with Docker and Project-Specific Configuration

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This Docker command illustrates how to run a separate multi-mcp instance for a specific project. It mounts custom configuration and memory volumes and maps ports for isolated project execution.

```bash
# Project A
docker run -d -p 8080:8080 \
  --name multi-mcp-project-a \
  -v $(pwd)/project-a-config:/app/mcp.json \
  -v $(pwd)/project-a-memory:/app/memory \
  multi-mcp:latest --transport sse --host 0.0.0.0
```

--------------------------------

### Run Multi-MCP in STDIO Mode

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Execute the main script using uv in STDIO mode for CLI-style, pipe-based communication. Useful for chaining local tools or agents.

```bash
uv run main.py --transport stdio
```

--------------------------------

### Add Knowledge Graph Server using cURL

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Use this cURL command to add a new knowledge graph server instance for a specific project. Ensure the JSON payload correctly specifies the command and arguments, including the memory path.

```bash
curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge-graph-project-xyz": {
      "command": "npx",
      "args": ["-y", "@shaneholloman/mcp-knowledge-graph", "--memory-path", "./memory/project-xyz.jsonl"]
    }
  }'
```

--------------------------------

### Apply Kubernetes Deployment Manifest

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Deploys the Multi-MCP application to the Kubernetes cluster using the provided YAML manifest.

```bash
kubectl apply -f examples/k8s/multi-mcp.yaml
```

--------------------------------

### Weather Service Server (Python)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Defines a weather service server using FastMCP that retrieves weather data via an HTTP call to the OpenWeatherMap API. Requires the OPENWEATHER_API_KEY environment variable.

```python
from mcp.server.fastmcp import FastMCP
import requests
import os

mcp = FastMCP("Weather")

@mcp.tool()
async def get_weather(location: str) -> dict:
    """Get weather for location via HTTP call."""
    api_key = os.environ["OPENWEATHER_API_KEY"]
    url = f"http://api.openweathermap.org/data/2.5/weather?q={location}&appid={api_key}&units=metric"
    try:
        response = requests.get(url)
        response.raise_for_status()
        data = response.json()
        return {
            "temperature": data["main"]["temp"],
            "weather": data["weather"][0]["description"],
            "humidity": data["main"]["humidity"],
            "wind_speed": data["wind"]["speed"]
        }
    except requests.exceptions.RequestException as e:
        return {"error": str(e)}

if __name__ == "__main__":
    mcp.run()
```

--------------------------------

### Add a New MCP Server via HTTP POST

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Dynamically add a new MCP server at runtime using an HTTP POST request. The request body should be a JSON object specifying the server configuration.

```bash
curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  --data @add_server.json
```

--------------------------------

### Add Knowledge Graph Server via API

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This command adds a knowledge graph server to Multi-MCP using its API. It specifies the command to run the knowledge graph server and its memory path.

```bash
curl -X POST http://localhost:8080/mcp_servers \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge-graph": {
      "command": "npx",
      "args": ["-y", "@shaneholloman/mcp-knowledge-graph", "--memory-path", "./memory/multi-mcp-knowledge.jsonl"]
    }
  }'
```

--------------------------------

### Run Multi-MCP in SSE Mode

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Execute the main script using uv in SSE mode to run an HTTP SSE server. This is useful for remote access, browser agents, and network-based tools.

```bash
uv run main.py --transport sse
```

--------------------------------

### Kubernetes Deployment (YAML)

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Configuration for deploying Multi-MCP to a Kubernetes cluster, exposing it via a NodePort service.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: multi-mcp-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: multi-mcp
  template:
    metadata:
      labels:
        app: multi-mcp
    spec:
      containers:
      - name: multi-mcp
        image: your-dockerhub-username/multi-mcp:latest # Replace with your image
        ports:
        - containerPort: 8080

---

apiVersion: v1
kind: Service
metadata:
  name: multi-mcp-service
spec:
  selector:
    app: multi-mcp
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
      nodePort: 30080 # Example NodePort, adjust as needed
  type: NodePort
```

--------------------------------

### Run Multi-MCP Docker Container Locally

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/README.md

Run the built Docker container locally with port exposure. This command is part of the Docker deployment process.

```bash
make docker-run
```

--------------------------------

### Production Systemd Service for Multi-MCP

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Configures a systemd service for running Multi-MCP in production, specifying user, working directory, environment variables, and security options. Ensure paths and user/group are correctly set.

```ini
[Unit]
Description=Multi-MCP Server with Knowledge Graph
After=network.target

[Service]
Type=simple
User=multimcp
Group=multimcp
WorkingDirectory=/opt/multi-mcp
Environment=MEMORY_PATH=/opt/multi-mcp/memory/knowledge-graph.jsonl
ExecStart=/opt/multi-mcp/.venv/bin/uv run main.py --transport sse --host 0.0.0.0 --port 8080
Restart=always
RestartSec=10

# Security
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/opt/multi-mcp/memory

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Kubernetes Deployment and Service for Multi-MCP

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Defines the Kubernetes Deployment and Service resources for deploying the multi-mcp application. Ensure the image name and tag match your build.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: multi-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: multi-mcp
  template:
    metadata:
      labels:
        app: multi-mcp
    spec:
      containers:
      - name: multi-mcp
        image: multi-mcp:latest
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: multi-mcp-service
spec:
  type: NodePort
  selector:
    app: multi-mcp
  ports:
  - port: 8080
    targetPort: 8080
    nodePort: 30080

```

--------------------------------

### MCP Server Configuration JSON

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

JSON configuration file format for defining backend MCP servers. Supports both command-based (STDIO) and URL-based (SSE) servers. Environment variables can be set for command-based servers.

```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["./tools/get_weather.py"],
      "env": {
        "OPENWEATHER_API_KEY": "your-api-key"
      }
    },
    "calculator": {
      "command": "python",
      "args": ["./tools/calculator.py"]
    },
    "remote_service": {
      "url": "http://127.0.0.1:9080/sse"
    }
  }
}
```

--------------------------------

### Docker Compose for Multi-MCP Services

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

Defines multiple Multi-MCP services with distinct ports, volumes, and environment variables for project isolation. Ensure project directories and config files exist.

```yaml
version: '3.8'
services:
  multi-mcp-project-a:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./projects/project-a/memory:/app/memory:rw
      - ./projects/project-a/config.json:/app/mcp.json:ro
    environment:
      - PROJECT_ID=project-a
      - MEMORY_PATH=/app/memory/knowledge-graph.jsonl
    restart: unless-stopped
    
  multi-mcp-project-b:
    build: .
    ports:
      - "8081:8080"
    volumes:
      - ./projects/project-b/memory:/app/memory:rw
      - ./projects/project-b/config.json:/app/mcp.json:ro
    environment:
      - PROJECT_ID=project-b
      - MEMORY_PATH=/app/memory/knowledge-graph.jsonl
    restart: unless-stopped
```

--------------------------------

### Run Specific Test File with Pytest

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/CLAUDE.md

Use this command to run a specific test file using Pytest, with verbose output enabled.

```bash
pytest -s tests/proxy_test.py
```

--------------------------------

### Configure Claude Code

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This command configures the Claude client to use the Multi-MCP server via SSE transport. Ensure the URL matches your Multi-MCP server's address.

```bash
claude mcp add --transport sse multi-mcp http://127.0.0.1:8080/sse
```

--------------------------------

### Enhanced Dockerfile for Multi-MCP Memory Persistence

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

An enhanced Dockerfile that adds a memory directory, sets permissions, and defines a volume for persistent memory, along with an environment variable for the memory path.

```dockerfile
# Building on existing multi-mcp Dockerfile
FROM multi-mcp:base

# Add memory directory
RUN mkdir -p /app/memory && chmod 755 /app/memory

# Volume for persistent memory
VOLUME ["/app/memory"]

# Environment for memory path
ENV MEMORY_PATH=/app/memory/knowledge-graph.jsonl
```

--------------------------------

### Kubernetes Service for Multi-MCP Load Balancing

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

A Kubernetes Service manifest to expose Multi-MCP via a LoadBalancer, directing traffic to the application pods.

```yaml
# Use existing K8s manifest
kubectl apply -f examples/k8s/multi-mcp.yaml

# Expose via LoadBalancer
apiVersion: v1
kind: Service
metadata:
  name: multi-mcp-lb
spec:
  type: LoadBalancer
  ports:
  - port: 8080
    targetPort: 8080
  selector:
    app: multi-mcp
```

--------------------------------

### Update MCP Tool Naming Convention

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This Python code demonstrates the fix for MCP tool naming conventions to comply with Claude's API requirements. It changes the separator from '::' to '_' to ensure tool names match the pattern '^[a-zA-Z0-9_-]{1,128}$'.

```python
# Before (line ~309)
return f"{server_name}::{item_name}"

# After  
return f"{server_name}_{item_name}"
```

```python
# Also updated split_key (line ~314)
return key.split("_", 1)  # was split("::", 1)
```

--------------------------------

### Remove MCP Server (DELETE /mcp_servers/{name})

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Remove a connected MCP server by its name. The server is disconnected, and its tools are unregistered. An error response is returned if the server name is not found.

```bash
curl -X DELETE http://localhost:8080/mcp_servers/unit_converter

# Response:
# {"message": "Client 'unit_converter' removed successfully"}

# Error response if server not found:
# {"error": "No client named 'unknown_server'"} (404)
```

--------------------------------

### Remove Knowledge Graph Server using cURL

Source: https://github.com/kfirtoledo/multi-mcp/blob/main/claude/250627114051/mcp-knowledge-graph-integration.md

This cURL command removes a previously added knowledge graph server instance. Replace 'knowledge-graph-project-xyz' with the actual server identifier.

```bash
curl -X DELETE http://localhost:8080/mcp_servers/knowledge-graph-project-xyz
```

--------------------------------

### DELETE /mcp_servers/{name} - Remove MCP Server

Source: https://context7.com/kfirtoledo/multi-mcp/llms.txt

Removes a connected MCP server by its name. This action disconnects the server and unregisters all of its associated tools.

```APIDOC
## DELETE /mcp_servers/{name} - Remove MCP Server

### Description
Remove a connected MCP server by name. The server is disconnected and all its tools are unregistered.

### Method
DELETE

### Endpoint
/mcp_servers/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the MCP server to remove.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the server was removed.

#### Error Response (404)
- **error** (string) - An error message if the specified server name is not found.

### Response Example
```json
{
  "message": "Client 'unit_converter' removed successfully"
}
```

### Error Response Example
```json
{
  "error": "No client named 'unknown_server'"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.