MCP Local Blueprint

Local MCP Server: A Complete Guide

This guide details how to build a local Model Context Protocol (MCP) server, configure it, and connect it to LLM clients like Claude Desktop and VS Code (Copilot).

What is MCP (Model Context Protocol)?

MCP is basically a standard for servers; it's just a web server following a certain template. It provides a standard interface through which LLMs can access tools and data. We basically allow the LLMs to autonomously do custom function calls and data retrieval when they think it's required.

This allows you to give an LLM "tools" — like the ability to roll dice, access a local file, or call a private API — that it can use to answer your questions.

How it Works: The Two-Part System

The key to understanding this setup is knowing that there are two separate components: the Server and the Gateway.

1. The MCP Server (e.g., dice-mcp-server)

* Analogy: The Chef 👨‍🍳 * This is the Docker image you build. It contains your actual code (e.g., a Python script) that knows how to perform the tasks, like roll_dice. This is the "kitchen" where the work gets done.

1. The MCP Gateway (e.g., docker/mcp-gateway)

* Analogy: The Manager 👔 * This is an official Docker image that acts as the "manager" or "front counter." It's the only thing the LLM client (Claude/VS Code) talks to. Its job is to read your configuration files and tell the correct "Chef" (your server) what to do.

You build the Chef and configure the Manager.

Architecture Flow

Here is a diagram showing how the user, the client, the gateway, and your server all interact.

graph TB
    subgraph user[" "]
        A["👤 USER

Ask AI anything"]
    end
    
    subgraph client[" "]
        B["💻 AI CLIENT

Claude Desktop
VS Code Copilot
Cursor
Any MCP-enabled app"]
    end
    
    subgraph gateway[" "]
        C["🌉 DOCKER MCP GATEWAY

Smart Orchestrator
📋 Manages multiple servers
🔌 Routes tool requests
⚙️ Handles connections"]
    end
    
    subgraph servers[" "]
        direction LR
        E1["🔧 SERVER 1
Database Tools"]
        E2["🔧 SERVER 2
API Integration"]
        E3["🔧 SERVER 3
File Processing"]
        E4["🔧 SERVER N
Your Custom Logic"]
    end
    
    subgraph examples[" "]
        direction LR
        F["💾 DATABASES
PostgreSQL
MongoDB
Redis
SQLite"]
        G["🌐 EXTERNAL APIS
GitHub
Slack
Payment APIs
Weather, Stock"]
        H["📁 FILE SYSTEMS
Read/Write files
Process CSVs
Generate PDFs
Image manipulation"]
        I["⚡ CUSTOM TOOLS
Business logic
Calculations
Validations
Automation"]
    end

    A ==>|"① Natural language query"| B
    B ==>|"② Discovers available tools
Sends tool request"| C
    C ==>|"③ Routes to appropriate server"| E1 & E2 & E3 & E4
    
    E1 -.->|"accesses"| F
    E2 -.->|"accesses"| G
    E3 -.->|"accesses"| H
    E4 -.->|"accesses"| I
    
    E1 & E2 & E3 & E4 ==>|"④ Executes & returns results"| C
    C ==>|"⑤ Aggregates responses"| B
    B ==>|"⑥ Natural language answer"| A

    classDef userStyle fill:#FF6B6B,stroke:#C92A2A,stroke-width:3px,color:#FFF
    classDef clientStyle fill:#4ECDC4,stroke:#0B7285,stroke-width:3px,color:#FFF
    classDef gatewayStyle fill:#45B7D1,stroke:#1971C2,stroke-width:3px,color:#FFF
    classDef serverStyle fill:#A78BFA,stroke:#6D28D9,stroke-width:2px,color:#FFF
    classDef exampleStyle fill:#FFA07A,stroke:#E8590C,stroke-width:2px,color:#FFF
    
    class A userStyle
    class B clientStyle
    class C gatewayStyle
    class E1,E2,E3,E4 serverStyle
    class F,G,H,I exampleStyle

Prerequisites Check

* Docker Desktop installed and running. * An MCP Client (e.g., Claude Desktop or VS Code with Copilot). * Enable Docker MCP Toolkit: 1. Open Docker Desktop. 2. Go to Settings → Beta Features. 3. Enable "Docker MCP Toolkit". 4. Click Apply & Restart.

Step 1: Build Your Tool Server (The "Chef")

First, you need to build the Docker image that contains your actual tool's code.

# Clone the example repository
git clone https://github.com/chaitanyakartik/local_MCP_template.git
cd src

# Build the Docker image, this creates a local image named "dice-mcp-server"
docker build -t dice-mcp-server .

Step 2: Create Your Configuration Files (The "Menu")

This is the most critical part. You must create two files in a specific folder to tell the "Manager" (the Gateway) about your "Chef" (the dice-mcp-server).

Go to your home folder (e.g., /Users/your-name/ or C:\Users\your-name\). Find or create the hidden .docker folder, and inside it, create an mcp folder.

The full path will be:

* macOS: /Users/your-name/.docker/mcp * Windows: C:\Users\your-name\.docker\mcp

Inside this mcp folder, create the following:

1\. The Registry File (The "Enable" List)

This file tells the Gateway *which* of your custom servers to turn on.

* Create this file: ~/.docker/mcp/registry.yaml * Paste this exact content:

      dice:
        ref: ""

*(Note: The ref: must be indented with two spaces.)*

2\. The Catalog File (The "Menu")

This file describes your server and its tools.

* Create this folder: ~/.docker/mcp/catalogs/ * Create this file: ~/.docker/mcp/catalogs/custom.yaml * Paste this exact content:

    version: 2
    name: custom
    displayName: Custom MCP Servers
    registry:
      dice:
        description: "Dice rolling for tabletop games"
        title: "Dice Roller"
        type: server
        dateAdded: "2025-01-01T00:00:00Z"
        image: dice-mcp-server:latest
        ref: ""
        tools:
          - name: flip_coin
          - name: roll_dice
          - name: roll_custom
          - name: roll_stats
          - name: roll_advantage
          - name: roll_disadvantage
          - name: roll_check
          - name: roll_initiative
        metadata:
          category: productivity
          tags:
            - gaming
            - dice
            - randomization

Step 3: Connect the LLM Client (The "Manager")

This is where we tell your client (Claude or VS Code) how to run the "Manager" (the Gateway). We will use an explicit command that *cannot fail* to find your config files.

First, get the full, absolute path to your mcp folder (e.g., /Users/chaitanyakartik/.docker/mcp or C:\Users\YourUser\.docker\mcp).

Option A: Connect to Claude Desktop

1. Open your Claude Desktop configuration file:

* macOS: ~/Library/Application Support/Claude/claude_desktop_config.json * Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Paste the following JSON. You must replace YOUR_FULL_PATH_HERE with your actual path.

    {
      "mcpServers": {
        "docker-mcp-gateway-explicit": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-v", "/var/run/docker.sock:/var/run/docker.sock",
            
            /*
             THIS IS THE CRITICAL LINE.
             It maps your local config folder into the container.
            */
            "-v", "YOUR_FULL_PATH_HERE:/mcp",
            
            "docker/mcp-gateway",
            "--registry=/mcp/registry.yaml",
            "--catalog=/mcp/catalogs/docker-mcp.yaml",
            "--catalog=/mcp/catalogs/custom.yaml",
            "--transport=stdio"
          ]
        }
      }
    }

* Windows Users: Remember to use double backslashes (\\) for your path, e.g., "C:\\Users\\YourUser\\.docker\\mcp:/mcp".

Option B: Connect to VS Code (Copilot)

1. In VS Code, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).

1. Run the command MCP: Open User Configuration.

1. This will open your mcp.json file.

1. Paste the following JSON. You must replace YOUR_FULL_PATH_HERE with your actual path.

    {
      "servers": {
        "docker-mcp-gateway-explicit": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-v",
            "/var/run/docker.sock:/var/run/docker.sock",

            /*
             THIS IS THE CRITICAL LINE.
             It maps your local config folder into the container.
            */
            "-v",
            "YOUR_FULL_PATH_HERE:/mcp",

            "docker/mcp-gateway",
            "--registry=/mcp/registry.yaml",
            "--catalog=/mcp/catalogs/docker-mcp.yaml",
            "--catalog=/mcp/catalogs/custom.yaml",
            "--transport=stdio"
          ],
          "type": "stdio"
        }
      },
      "inputs": []
    }

* Windows Users: Remember to use double backslashes (\\) for your path, e.g., "C:\\Users\\YourUser\\.docker\\mcp:/mcp".

Step 4: Test It\!

1. Completely quit and restart Claude Desktop or VS Code.
2. Open a new chat.
3. Click the Tools icon (or press Cmd/Ctrl+I).
4. You should see your gateway listed: docker-mcp-gateway-explicit.
5. Under it, you should see all your dice tools: roll_dice, flip_coin, etc.
6. Try it\! "Roll 2d6+3 for damage"

If it works, you have successfully built and configured a local MCP server.

Acknowledgements

This guide and the dice-mcp-server example are heavily based on the excellent tutorial and code provided by NetworkChuck.

• GitHub Repository:
• Original YouTube Tutorial: you need to learn MCP RIGHT NOW!! (Model Context Protocol)