mcp-sub-agent
Exposes OpenAI-compatible chat models as sub-agents, allowing MCP clients to call configured agents with tasks, optional context, and images and receive text responses via the chat completions API.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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-agentFrom 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:
the
--config PATHCLI argument,the
MCP_SUB_AGENT_CONFIGenvironment variable,./sub-agents.yamlin 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 |
| string | yes | Unique agent name; becomes the MCP tool name (sanitized). |
| string | yes | Model name to send to the chat completions endpoint. |
| string | yes | Tool description shown to the calling agent. |
| string | yes | System prompt for the sub-agent. |
| string | no | OpenAI-compatible API base URL (defaults to OpenAI's). |
| string | no | API key. When omitted, a placeholder is sent (useful for local servers without auth). |
| number | no | Request timeout in seconds (default: 300). |
| integer | no | Number of retries for failed requests (default: 2). |
| number | no | Sampling temperature, 0.0–2.0. |
| integer | no | Maximum completion tokens. |
| integer | no | Maximum size in bytes for a local image file attached to a task (default: 10485760, i.e. 10 MB). |
| 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 ofVAR; a missing variable is an error.${VAR:-default}— replaced with the value ofVAR, ordefaultwhen 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.yamlThe 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.yamlClaude 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 anhttp(s)URL, adata: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 base64data:URIs in the chat completions request. Files larger thanmax_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 -vTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Create images & video from any MCP agent — 17 models, spend limits, one URL.
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- AlicenseAqualityCmaintenanceWraps OpenAI-compatible text-to-image APIs as MCP tools, enabling image generation directly from conversations in Claude Code, Codex, Cursor, or Claude Desktop using the user's own API key.61Apache 2.0
- AlicenseAqualityCmaintenanceEnables text-only LLMs to analyze images by sending files, URLs, or data URIs to a separate OpenAI-compatible vision model through a single MCP tool.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables OpenAI-compatible clients to access external tools, APIs, repositories, and data sources through MCP with allowlisting, approval, and argument validation, deployable as a FastAPI service or Python library.MIT
- AlicenseNot gradedqualityBmaintenanceEnables any MCP-compatible agent to generate and edit images using an existing Codex/ChatGPT subscription, exposing image generation and editing as tool calls.27 npmMIT