mcpbridge

# 1. Create a config file
cat > config.yaml << 'EOF'
server:
  name: weather-mcp
  version: 1.0.0
  transport: stdio

sources:
  - type: get_endpoint
    name: get_weather
    description: >
      Returns current weather for a location given latitude and longitude.
      Use when the user asks about weather or temperature.
    url: https://api.open-meteo.com/v1/forecast
    query_params:
      - name: latitude
        type: float
        required: true
      - name: longitude
        type: float
        required: true
    response_field: current_weather
EOF

# 2. Validate it
npx mcpbridge validate config.yaml

# 3. Add to Claude Desktop (see below) and ask: "What's the weather in Amsterdam?"

docker run \
  -v ./config.yaml:/app/config.yaml \
  --env-file .env \
  mcpbridge/mcpbridge

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcpbridge", "run", "/absolute/path/to/config.yaml"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

- type: db_query
  name: get_orders               # snake_case, becomes tool name
  description: >                 # LLM reads this — be specific about when to use it
    Returns all orders for a specific user.
    Use when asked about order history or purchases.
  query: >
    SELECT id, product, amount, status
    FROM orders
    WHERE user_id = :user_id
  params:
    - name: user_id
      type: integer              # string | integer | boolean | float
      required: true
  connection: "${DATABASE_URL}"  # always an env var — never hardcode
  allow_write: false             # default: false — set true only for explicit write tools

- type: get_endpoint
  name: get_weather
  description: >
    Returns current weather forecast for a given latitude and longitude.
    Use when the user asks about weather or temperature.
  url: https://api.open-meteo.com/v1/forecast
  query_params:
    - name: latitude
      type: float
      required: true
    - name: longitude
      type: float
      required: true
  headers:
    Authorization: "Bearer ${API_KEY}"   # env var substitution in headers too
  response_field: current_weather        # optional: extract nested field (dot notation)
  timeout: 30                            # seconds, default: 30

- type: knowledge_base
  name: company_faq
  description: >
    Internal company FAQ and policies.
    Use when the user asks about company procedures or rules.
  path: ./kb/                    # file or directory (recursive)
  strategy: chunk                # full | chunk
  chunk_size: 800                # chars per chunk (default: 800)
  chunk_overlap: 100             # overlap between chunks (default: 100)

server:
  name: my-company-mcp
  version: 1.0.0
  transport: stdio

sources:
  - type: get_endpoint
    name: get_weather
    description: >
      Returns current weather for a location.
      Use when the user asks about weather.
    url: https://api.open-meteo.com/v1/forecast
    query_params:
      - name: latitude
        type: float
        required: true
      - name: longitude
        type: float
        required: true
    response_field: current_weather

  - type: db_query
    name: get_orders
    description: >
      Returns orders for a specific user.
      Use when the user asks about their order history.
    query: "SELECT id, product, amount, status FROM orders WHERE user_id = :user_id"
    params:
      - name: user_id
        type: integer
        required: true
    connection: "${DATABASE_URL}"

  - type: knowledge_base
    name: company_faq
    description: >
      Company FAQ and internal policies.
      Use when the user asks about company procedures.
    path: ./kb/
    strategy: chunk
    chunk_size: 800

# Install
npm install -g mcpbridge
# or without installing:
npx mcpbridge

# Validate a config
mcpbridge validate config.yaml

# Run the server
DATABASE_URL=sqlite://./dev.db mcpbridge run config.yaml

# Build locally
docker build -t mcpbridge .

# Run with a config
docker run \
  -v ./config.yaml:/app/config.yaml \
  -v ./kb:/app/kb \
  --env-file .env \
  mcpbridge

# Or with docker-compose (includes PostgreSQL)
docker compose up