Skip to main content
Glama
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
```