MCP Servers

🔌 MCP Servers (Custom Tools)

Steps can declare MCP stdio servers to add custom tools on demand. Claude will see these tools alongside its built-in tools (Read, Write, Bash, etc.).

graph LR
    A[CodeGenesis] -->|"--mcp-config"| B[Claude CLI]
    B --> C[MCP Server 1]
    B --> D[MCP Server 2]
    C -->|stdio| E["🔧 custom tool A"]
    D -->|stdio| F["🔧 custom tool B"]

Loading

---

📍 Step-level

steps:
  - name: "Analyze codebase"
    prompt: "Use the analyzer tool to check for issues"
    mcp_servers:
      analyzer:
        command: "python"
        args: ["tools/analyzer_server.py"]
        env:
          MODE: "strict"
    allowed_tools:
      - "mcp__analyzer__run_analysis"

🌐 Global (all steps)

settings:
  mcp_servers:
    shared-db:
      command: "python"
      args: ["tools/db_server.py"]
      env:
        DB_HOST: "{{db_host}}"

steps:
  - name: "Query data"
    prompt: "Use the database tool to fetch user stats"
    allowed_tools:
      - "mcp__shared-db__query"

📦 In context bundles

# contexts/data-analyst/agent.yml
system_prompt: "You are a data analyst with access to the database."
allowed_tools:
  - "mcp__db__query"
  - "mcp__db__schema"
mcp_servers:
  db:
    command: "dotnet"
    args: ["run", "--project", "tools/DbServer"]

---

🔀 Merge Order

When multiple levels define MCP servers, they merge with later sources winning on key collision:

graph LR
    A["1️⃣ Global<br/>(settings.mcp_servers)"] --> B["2️⃣ Context Bundle<br/>(agent.yml)"]
    B --> C["3️⃣ Step-level<br/>(steps[].mcp_servers)"]
    style C fill:#2d5016,color:#fff

Loading

---

⚙️ Configuration Fields

Field	Required	Description
command	✅	Executable to run ("python", "dotnet", "node")
args	❌	Command-line arguments
env	❌	Environment variables for the MCP process
description	❌	Human-readable description of what this server does (injected into system prompt)
parameters	❌	Documents the parameters the server's tools accept (injected into system prompt)

Tip

All fields support template variables ({{variable}}), resolved from pipeline inputs at build time.

---

📝 Tool Documentation (description & parameters)

MCP servers expose tools via the MCP protocol, but the LLM may not know when or how to use them. Add description and parameters to give the LLM context:

settings:
  mcp_servers:
    jira:
      command: "npx"
      args: ["-y", "@anthropic/mcp-jira"]
      description: "Search and manage Jira tickets"
      parameters:
        project_key:
          description: "The Jira project key"
          example: "PROJ-123"
        assignee:
          description: "Filter by assignee email"
      env:
        JIRA_TOKEN: "{{jira_token}}"

Parameter fields

Field	Description
description	What this parameter does
example	Example value (shown inline)

How it works

When a step has MCP servers with description or parameters, CodeGenesis automatically appends an Available MCP Tools section to the system prompt:

## Available MCP Tools

### jira

Search and manage Jira tickets

**Parameters:**

- `project_key`: The Jira project key (example: `PROJ-123`)
- `assignee`: Filter by assignee email

Note

description and parameters are YAML-only metadata. They are injected into the system prompt — they are not written to the --mcp-config JSON sent to Claude CLI.

Tip

Servers without description or parameters are silently skipped — no noise in the system prompt.

---

🔧 How It Works

1. CodeGenesis writes the MCP server config to a temporary JSON file
2. Passes --mcp-config <path> to the Claude CLI process
3. Claude CLI starts the MCP server(s), making their tools available
4. When the step finishes, servers are terminated and the temp file is cleaned up

Note

Each step invocation gets its own temp file (GUID-based naming), so parallel steps are fully thread-safe.