Skip to content

EXAMPLES.md

Latest commit

 

History

History
475 lines (380 loc) · 8.08 KB

EXAMPLES.md

File metadata and controls

475 lines (380 loc) · 8.08 KB

Usage Examples

Overview

This document provides real-world configuration examples for common MCP servers. Each example includes installation instructions, configuration, and use cases.

Git MCP Server

Using NPM (Recommended)

The most common way to run the Git MCP server.

Installation:

npm install -g @modelcontextprotocol/server-git

Configuration:

servers:
  git:
    name: "git"
    binary: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-git"
    timeout: 60s
    max_restarts: 5
    auto_start: false

Use Cases:

  • Repository operations
  • File read/write in repos
  • Git commands (diff, log, status)
  • Commit history analysis

Args Explanation:

  • -y: Skip confirmation prompts
  • @modelcontextprotocol/server-git: Package name

Using Docker

Run Git MCP in an isolated container.

Configuration:

servers:
  git:
    name: "git"
    binary: "docker"
    args:
      - "run"
      - "-i"
      - "--rm"
      - "mcp/git-server"
    timeout: 60s
    auto_start: false

Benefits:

  • Isolated environment
  • No local dependencies
  • Easy to clean up

Filesystem MCP Server

Using Node.js

Installation:

npm install -g @modelcontextprotocol/server-filesystem

Configuration:

servers:
  filesystem:
    name: "filesystem"
    binary: "/usr/bin/node"
    args:
      - "/path/to/mcp-filesystem-server/index.js"
      - "--allowed-directory=/data"
    env:
      HOME: "/home/user"
    timeout: 30s
    max_restarts: 3
    auto_start: true

Security:

  • --allowed-directory: Restricts access to specific directories
  • Never expose / or sensitive directories
  • Use read-only mode when possible

Recommended:

servers:
  filesystem:
    binary: "/usr/bin/node"
    args:
      - "/path/to/server/index.js"
      - "--allowed-directory=/data"
      - "--read-only"

Using uvx (Python)

Alternative installation using uvx.

Installation:

pip install mcp-server-filesystem

Configuration:

servers:
  filesystem:
    name: "filesystem"
    binary: "uvx"
    args:
      - "mcp-server-filesystem"
      - "--allowed-directory=/home/user/projects"
    timeout: 30s
    max_restarts: 3

Use Cases:

  • File operations
  • Directory browsing
  • Document processing
  • Code analysis

Memory MCP Server

Using Docker

Temporary storage for sessions and state.

Configuration:

servers:
  memory:
    name: "memory"
    binary: "docker"
    args:
      - "run"
      - "-i"
      - "--rm"
      - "mcp/memory-server:latest"
    timeout: 30s
    auto_start: false

Use Cases:

  • Key-value storage
  • Session memory
  • Temporary data
  • Cache

Custom Binary

Local Development

Run your own MCP server.

Configuration:

servers:
  custom:
    name: "custom"
    binary: "/home/user/my-mcp-server"
    args:
      - "--port"
      - "9000"
      - "--config"
      - "/etc/myserver/config.json"
    env:
      MY_SECRET: "${MY_SECRET}"
    timeout: 60s
    max_restarts: 3
    auto_start: false

Requirements:

  • Binary must be executable (chmod +x)
  • Binary must output JSON-RPC to stdout
  • Each message must end with newline (\n)

Example: Custom Tool

servers:
  calculator:
    name: "calculator"
    binary: "./calc-server"
    args:
      - "--port"
      - "9001"
    timeout: 30s
    max_restarts: 2
    auto_start: false

Multi-Server Setup

3-Server Production Setup

Running multiple servers simultaneously.

Configuration:

bridge:
  port: 8080
  allowed_origins:
    - http://localhost:3000
  connection_limit: 10
  request_size_limit: 2097152

servers:
  git:
    name: "git"
    binary: "npx"
    args: ["-y", "@modelcontextprotocol/server-git"]
    timeout: 60s
    max_restarts: 5
    auto_start: true

  filesystem:
    name: "filesystem"
    binary: "uvx"
    args: ["mcp-server-filesystem", "--allowed-directory=/data"]
    timeout: 30s
    max_restarts: 3
    auto_start: true

  memory:
    name: "memory"
    binary: "docker"
    args: ["run", "-i", "mcp/memory-server"]
    timeout: 30s
    max_restarts: 2
    auto_start: false

Namespace Routing:

  • Git tools: /mcp/git/tools/call
  • Filesystem tools: /mcp/filesystem/tools/call
  • Memory tools: /mcp/memory/tools/call

Benefits:

  • Isolated server processes
  • Independent restart policies
  • Separate timeouts

Resource Allocation

servers:
  git:
    auto_start: true  # Always ready
    max_restarts: 5   # Forgiving
    
  filesystem:
    auto_start: true  # Always ready
    max_restarts: 3   # Moderate
    
  memory:
    auto_start: false # Start on demand
    max_restarts: 2   # Strict

Production Deployment

Systemd Service

File: /etc/systemd/system/mcp-bridge.service

[Unit]
Description=MCP HTTP Bridge
After=network.target

[Service]
Type=simple
User=bridge
WorkingDirectory=/opt/mcp-bridge
ExecStart=/opt/mcp-bridge/bin/bridge --config /etc/mcp-bridge/config.yaml
Restart=on-failure
RestartSec=10
Environment="NODE_ENV=production"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable mcp-bridge
sudo systemctl start mcp-bridge

Monitor:

sudo systemctl status mcp-bridge
sudo journalctl -u mcp-bridge -f

Advanced Examples

Environment Variable Interpolation

servers:
  git:
    env:
      REPO_PATH: "/data/${REPO_NAME}"
      API_KEY: "${API_KEY}"
      DEBUG: "${DEBUG:-false}"  # Default value if not set

Behavior:

  • ${VAR_NAME} - Environment variable
  • ${VAR:-default} - Environment variable with default
  • No shell expansion

Per-Server Timeouts

servers:
  fast:
    timeout: 10s  # Fast server
  slow:
    timeout: 120s  # Slow server (filesystem)

High Restart Limits

servers:
  unstable:
    max_restarts: 10  # Allow more restarts
    timeout: 60s

Custom Environment

servers:
  custom:
    env:
      HOME: "/home/user"
      PATH: "/usr/local/bin:/usr/bin"
      NODE_ENV: "production"
      API_KEY: "${API_KEY}"

Troubleshooting Examples

Binary Not Found

Wrong:

binary: "my-server"  # Not in PATH

Right:

binary: "/usr/local/bin/my-server"  # Absolute path

Permission Denied

Fix:

chmod +x /path/to/binary

Port Already in Use

Change port:

bridge:
  port: 8081  # Use different port

Subprocess Won't Start

Check:

# Verify binary exists
which npx

# Check permissions
ls -la /path/to/binary

# Test manually
npx -y @modelcontextprotocol/server-git

Best Practices

Security

  1. Use absolute paths for binaries
  2. Restrict allowed_directory for filesystem server
  3. Use allowed_origins to limit CORS
  4. Use allowed_args to restrict server arguments
  5. Argument sanitization is always enabled by default

Performance

  1. Set auto_start: true for frequently-used servers
  2. Adjust timeout based on server characteristics
  3. Use connection_limit appropriately
  4. Monitor restart counts

Reliability

  1. Set reasonable max_restarts limits
  2. Use idle_timeout to clean up connections
  3. Monitor subprocess health via /health/{namespace}
  4. Enable logging for troubleshooting

Quick Reference

Minimum Configuration

bridge:
  port: 8080
  allowed_origins:
    - http://localhost:3000

servers:
  git:
    name: "git"
    binary: "npx"
    args: ["-y", "@modelcontextprotocol/server-git"]

Recommended Configuration

bridge:
  port: 8080
  allowed_origins:
    - http://localhost:3000
  request_timeout: 30s
  idle_timeout: 5m
  connection_limit: 10

servers:
  git:
    name: "git"
    binary: "npx"
    args: ["-y", "@modelcontextprotocol/server-git"]
    timeout: 60s
    max_restarts: 5
    auto_start: true

  filesystem:
    name: "filesystem"
    binary: "/usr/bin/node"
    args:
      - "/path/to/server"
      - "--allowed-directory=/data"
    timeout: 30s
    max_restarts: 3
    auto_start: true

For configuration reference, see CONFIG.md. For API details, see API.md.