mcp-sub-agent
by digifac
README.md
# mcp-sub-agent
An [MCP](https://modelcontextprotocol.io) server that exposes any
[OpenAI-compatible](https://platform.openai.com/docs/api-reference) 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
```bash
pip install mcp-sub-agent
```
From source (development install):
```bash
git clone <repo-url>
cd mcp-sub-agent
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
```
## 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`](sub-agents-template.yaml).
### Example
```yaml
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
```bash
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
```bash
claude mcp add mcp-sub-agent -- /path/to/venv/bin/mcp-sub-agent --config /path/to/sub-agents.yaml
```
### Claude Desktop / generic stdio client
```json
{
"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
```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -v
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues