MCP Server Configuration

MCP Server Configuration

Status: ✅ Complete

Last Updated: December 6, 2025

---

Overview

This guide covers configuring MCP servers in RiceCoder. MCP servers are external processes that provide tools via the Model Context Protocol.

Configuration File

Location: .ricecoder/mcp-servers.yaml

Format: YAML

Configuration Structure

servers:
  - id: <server-id>
    name: <display-name>
    command: <executable>
    args:
      - <arg1>
      - <arg2>
    env:
      <VAR_NAME>: <value>
    timeout_ms: <milliseconds>
    auto_reconnect: true
    max_retries: <number>

Field Reference

id (required)

Unique identifier for the server. Used in tool IDs and logging.

Format: kebab-case

Example: database-server, api-service, custom-tools

name (required)

Display name for the server. Used in UI and documentation.

Format: Any string

Example: Database Tools, API Service, Custom Tools

command (required)

Executable to run. Can be:

• Absolute path: /usr/local/bin/server
• Relative path: ./server
• Command in PATH: uvx, node, python

Examples:

• uvx - Run Python package via uv
• node - Run Node.js script
• python - Run Python script
• /usr/local/bin/mcp-server - Absolute path

args (optional)

Command-line arguments passed to the executable.

Format: Array of strings

Example:

args:
  - database-mcp-server@latest
  - --port
  - "8000"

env (optional)

Environment variables to set for the server process.

Format: Key-value pairs

Example:

env:
  DB_URL: postgresql://localhost/mydb
  API_KEY: ${API_KEY}  # Reference environment variable
  DEBUG: "true"

timeout_ms (optional)

Timeout for tool execution in milliseconds.

Default: 5000

Range: 1000 - 60000

Example: timeout_ms: 10000

auto_reconnect (optional)

Automatically reconnect on server failure.

Default: true

Example: auto_reconnect: true

max_retries (optional)

Maximum number of reconnection attempts.

Default: 3

Range: 1 - 10

Example: max_retries: 5

Examples

Example 1: Database Server

servers:
  - id: database-server
    name: Database Tools
    command: uvx
    args:
      - database-mcp-server@latest
    env:
      DB_URL: postgresql://localhost/mydb
      DB_USER: admin
      DB_PASSWORD: ${DB_PASSWORD}
    timeout_ms: 5000
    auto_reconnect: true
    max_retries: 3

Example 2: API Service

servers:
  - id: api-server
    name: API Tools
    command: node
    args:
      - ./api-server.js
      - --port
      - "3000"
    env:
      API_KEY: ${API_KEY}
      API_URL: https://api.example.com
    timeout_ms: 10000
    auto_reconnect: true
    max_retries: 5

Example 3: Python Server

servers:
  - id: python-server
    name: Python Tools
    command: python
    args:
      - -m
      - mcp_server
      - --config
      - ./config.json
    env:
      PYTHONPATH: ./lib
      LOG_LEVEL: INFO
    timeout_ms: 5000
    auto_reconnect: true
    max_retries: 3

Example 4: Multiple Servers

servers:
  - id: database-server
    name: Database Tools
    command: uvx
    args:
      - database-mcp-server@latest
    env:
      DB_URL: postgresql://localhost/mydb
    timeout_ms: 5000
    auto_reconnect: true
    max_retries: 3

  - id: api-server
    name: API Tools
    command: node
    args:
      - ./api-server.js
    env:
      API_KEY: ${API_KEY}
    timeout_ms: 10000
    auto_reconnect: true
    max_retries: 5

  - id: custom-server
    name: Custom Tools
    command: /usr/local/bin/custom-mcp-server
    env:
      CONFIG_PATH: ./custom-config.yaml
    timeout_ms: 5000
    auto_reconnect: true
    max_retries: 3

Configuration Loading

Configurations are loaded from multiple sources in priority order:

1. Project-level: .ricecoder/mcp-servers.yaml
2. User-level: ~/.ricecoder/mcp-servers.yaml
3. Built-in defaults: Minimal default configuration

Later configurations override earlier ones.

Environment Variables

Environment variables can be referenced in configuration using ${VAR_NAME} syntax:

servers:
  - id: database-server
    name: Database Tools
    command: uvx
    args:
      - database-mcp-server@latest
    env:
      DB_URL: ${DATABASE_URL}
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}

Hot-Reload

Configuration changes are automatically detected and applied without restarting RiceCoder:

# Edit configuration
nano .ricecoder/mcp-servers.yaml

# Changes are automatically applied
# Or manually trigger reload
ricecoder config reload

Validation

Configuration is validated on load:

# Validate configuration
ricecoder config validate

# Output:
# ✓ Configuration is valid
# ✓ All servers are reachable
# ✓ All environment variables are set

Troubleshooting

Server Won't Start

Error: Failed to start server 'database-server': command not found

Solutions:

1. Check command is in PATH: which uvx
2. Use absolute path: /usr/local/bin/uvx
3. Install command: pip install uv

Connection Timeout

Error: Server 'database-server' connection timeout after 5000ms

Solutions:

1. Increase timeout_ms: timeout_ms: 10000
2. Check server is running: ps aux | grep server
3. Check network connectivity
4. Check server logs

Environment Variable Not Set

Error: Environment variable 'DB_PASSWORD' not set

Solutions:

1. Set environment variable: export DB_PASSWORD=secret
2. Use default value: DB_PASSWORD: ${DB_PASSWORD:-default}
3. Remove variable reference if not needed

Invalid Configuration

Error: Invalid configuration: missing required field 'command'

Solutions:

1. Check YAML syntax: yamllint .ricecoder/mcp-servers.yaml
2. Verify all required fields are present
3. Check indentation (YAML is whitespace-sensitive)

See Also

• MCP Integration
• Custom Tool Definition
• Permission Configuration
• Configuration Guide

---

Last updated: December 6, 2025