Skip to main content
Glama

mcp-sub-agent

An MCP server that exposes any OpenAI-compatible chat model as a sub-agent. Each agent defined in a YAML config file becomes an MCP tool that a parent agent (Claude Desktop, Claude Code, or any MCP client) can call with a task and optional context.

Installation

pip install mcp-sub-agent

From source (development install):

git clone <repo-url>
cd mcp-sub-agent
python -m venv .venv
.venv/bin/pip install -e ".[dev]"

Related MCP server: analyze-image-mcp

Configuration

The server reads a YAML config file. Its location is resolved in this order:

  1. the --config PATH CLI argument,

  2. the MCP_SUB_AGENT_CONFIG environment variable,

  3. ./sub-agents.yaml in the current working directory.

A starter template is provided in sub-agents-template.yaml.

Example

defaults:
  base_url: "https://api.openai.com/v1"
  api_key: "${OPENAI_API_KEY}"
  temperature: 0.2

agents:
  - name: "researcher"
    model: "gpt-4o"
    description: "A sub-agent that researches topics and returns concise, sourced summaries."
    system_prompt: |
      You are a research sub-agent. You answer the task given by your parent
      agent with concise, factual summaries. You do not make up facts.

  - name: "local-coder"
    model: "qwen2.5-coder"
    base_url: "http://localhost:8080/v1"   # per-agent override
    api_key: "${LOCAL_API_KEY:-none}"      # env var with a default
    description: "A local coding sub-agent for small refactoring tasks."
    system_prompt: "You are a coding sub-agent. You return only code and brief notes."

Fields

defaults (optional) provides shared values; every agent may override any of them. Per-agent values win.

Field

Type

Required

Description

name

string

yes

Unique agent name; becomes the MCP tool name (sanitized).

model

string

yes

Model name to send to the chat completions endpoint.

description

string

yes

Tool description shown to the calling agent.

system_prompt

string

yes

System prompt for the sub-agent.

base_url

string

no

OpenAI-compatible API base URL (defaults to OpenAI's).

api_key

string

no

API key. When omitted, a placeholder is sent (useful for local servers without auth).

timeout

number

no

Request timeout in seconds (default: 300).

max_retries

integer

no

Number of retries for failed requests (default: 2).

temperature

number

no

Sampling temperature, 0.0–2.0.

max_tokens

integer

no

Maximum completion tokens.

max_image_bytes

integer

no

Maximum size in bytes for a local image file attached to a task (default: 10485760, i.e. 10 MB).

extra_body

mapping

no

Extra fields merged into the chat completions request body.

Unknown fields are rejected. Agent names are sanitized into valid MCP tool names (anything other than letters, digits, - and _ becomes _, max 64 characters), and two agents that would map to the same tool name are a configuration error.

Environment variable expansion

Any string value in the config may reference environment variables:

  • ${VAR} — replaced with the value of VAR; a missing variable is an error.

  • ${VAR:-default} — replaced with the value of VAR, or default when the variable is unset or empty.

CLI usage

mcp-sub-agent                      # uses MCP_SUB_AGENT_CONFIG or ./sub-agents.yaml
mcp-sub-agent --config /path/to/sub-agents.yaml

The server speaks MCP over stdio. Configuration errors are reported on stderr with a non-zero exit code.

MCP client setup

Claude Code

claude mcp add mcp-sub-agent -- /path/to/venv/bin/mcp-sub-agent --config /path/to/sub-agents.yaml

Claude Desktop / generic stdio client

{
  "mcpServers": {
    "mcp-sub-agent": {
      "command": "/path/to/venv/bin/mcp-sub-agent",
      "args": ["--config", "/path/to/sub-agents.yaml"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

What the client sees

Each configured agent appears as a tool with the agent's (sanitized) name, its description, and three parameters:

  • task (required) — the task to perform.

  • context (optional) — additional context, constraints or background.

  • images (optional) — a list of images to attach for vision models. Each entry is an http(s) URL, a data: URI, or a local file path. Local files are read by the server, their MIME type is detected (PNG, JPEG, WEBP, GIF, BMP) and they are inlined as base64 data: URIs in the chat completions request. Files larger than max_image_bytes (default 10 MB) are rejected.

The tool returns the sub-agent's text response. Failures (API errors, empty or refused responses, unreadable or unsupported images) are returned to the client as tool errors.

Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -v

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers