LLM Subagent MCP

English | 繁體中文

A FastMCP server that wraps OpenAI-compatible Chat Completions APIs, with TAIWAN AI RAP as the initial provider. ChatGPT or Claude Code acts as the parent assistant, delegates text tasks such as summarization, translation, or code review to a third-party LLM, and incorporates the result.

This is a text task subagent. Each call is independent and has no conversation memory. The subagent receives only the explicitly supplied task, context, and instructions. It has no access to the parent assistant's files, terminal, or tools, and cannot execute tool calls requested by the model.

Installation and quick start

Windows PowerShell

Install uv first, then run the following from the project root. These commands use uv from PATH when available, falling back to its default location in the user directory:

$uv = if (Get-Command uv -ErrorAction SilentlyContinue) { 'uv' } else { Join-Path $env:USERPROFILE '.local\bin\uv.exe' }
$env:UV_PYTHON_INSTALL_DIR = Join-Path (Get-Location) '.uv-python'
& $uv --cache-dir .uv-cache sync --locked
Copy-Item .env.example .env

Set LLM_API_KEY in .env. Use the MCP list_models tool to find an available chat model, then set LLM_MODEL or pass model to delegate_task. The model list may also contain embedding or audio models that cannot be used with Chat Completions.

& $uv --cache-dir .uv-cache run --locked llm-subagent-mcp --config providers.toml

The stdio server waits for MCP client input. Clients such as Claude Code normally start it automatically. To check the installation:

.\.venv\Scripts\llm-subagent-mcp.exe --help

Linux / macOS (Bash / Zsh)

Install uv using the official installation instructions. Skip this step if uv is already installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal afterward. If your current shell cannot find uv, run export PATH="$HOME/.local/bin:$PATH". macOS users with Homebrew can also use brew install uv.

From the project root, create the environment and install dependencies. uv uses .python-version and downloads Python 3.12 if needed:

export UV_PYTHON_INSTALL_DIR="$PWD/.uv-python"
uv --cache-dir .uv-cache sync --locked
if [ ! -f .env ]; then
  cp .env.example .env
fi
chmod 600 .env

Edit .env and set LLM_API_KEY. Use list_models to find an available chat model, then set LLM_MODEL or specify model when calling the tool.

# Check the installed entry point
./.venv/bin/llm-subagent-mcp --help

# Start the stdio MCP server and wait for client input
uv --cache-dir .uv-cache run --locked llm-subagent-mcp --config providers.toml

These commands use the virtual environment directly; activation with source .venv/bin/activate is optional.

Related MCP server: DeepSeek Subagent MCP Server

Configuration

Existing process environment variables take precedence over .env. The server loads .env relative to the file passed to --config, so launching from a different working directory still finds the correct settings.

The default variable names are provider-neutral: LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL. For multiple providers, assign separate variable names through each provider's base_url_env, api_key_env, and model_env, such as OTHER_LLM_API_KEY.

Restart the MCP server after changing configuration. Add a provider by creating a [providers.NAME] section. Authentication defaults to Authorization: Bearer; the RAP profile uses x-api-key.

Tool callers cannot supply a base URL or API key directly. Those settings stay on the server, preventing individual tasks from redirecting credentials to arbitrary endpoints.

RAP's documentation describes authentication differently across pages: the API reference specifies Bearer authentication, while most usage-guide examples use x-api-key. Both are supported through auth_mode = "x-api-key" or "bearer". The RAP profile follows the usage guide. Both methods have not been verified with live account credentials, and the server does not automatically retry with a different authentication method.

MCP tools

• list_providers(): Returns configuration status, default models, and limits without exposing API keys.

• list_models(provider?): Calls the provider's /models endpoint and applies the model allowlist.

• delegate_task(task, context?, instructions?, provider?, model?, max_tokens?, temperature?): Calls /chat/completions and returns text, model, finish reason, a truncation flag, and token usage when supplied by the provider.

Defaults are four concurrent upstream requests, 100,000 input characters per task, and 4,096 output tokens per request. These limits are configurable in TOML.

The server omits temperature unless explicitly requested to improve compatibility across models. When supplied, it must be between 0 and 1, matching the RAP documentation.

Each task makes one non-streaming HTTP request with no automatic retries, avoiding hidden repeated billable requests. Limits apply per request and to concurrency; they are not daily spending limits or per-user quotas. HTTPX sends OpenAI-compatible JSON directly.

Cancellation propagates to the pending HTTP request. Whether the provider stops generation or billing depends on its implementation.

Example tool arguments:

{
  "task": "Review this function for bugs and suggest improvements.",
  "context": "<code read and supplied by the parent assistant>",
  "instructions": "Distinguish confirmed bugs from issues requiring further investigation.",
  "provider": "rap",
  "max_tokens": 2048
}

Claude Code: local stdio

Run the following from the project root. After installation, the client starts the virtual environment's executable directly without downloading packages at startup.

Windows PowerShell:

$projectRoot = (Get-Location).Path
$serverPath = Join-Path $projectRoot '.venv\Scripts\llm-subagent-mcp.exe'
$configPath = Join-Path $projectRoot 'providers.toml'
claude mcp add --transport stdio rap-subagent -- $serverPath --config $configPath

Linux / macOS:

project_root="$(pwd -P)"
claude mcp add --transport stdio rap-subagent -- \
  "$project_root/.venv/bin/llm-subagent-mcp" \
  --config "$project_root/providers.toml"

Alternatively, see examples/claude.mcp.json. This is a Windows example: replace C:\path\to\llm-subagent-mcp with the project's actual absolute path. On Linux / macOS, use .venv/bin/llm-subagent-mcp. Update the configuration if the project moves.

Example prompt:

Use rap-subagent's list_models tool to find an available chat model. Send the following content to delegate_task for summarization, then incorporate the result: …

This provides task delegation through MCP tools. It does not automatically change the model used by Claude Code's native subagents.

ChatGPT desktop: local stdio

According to the official OpenAI MCP documentation, supported ChatGPT desktop versions can add local stdio servers and share MCP configuration with Codex CLI on the same host.

Complete installation and set LLM_API_KEY in .env beside providers.toml. The desktop app starts the stdio process; no separate HTTP server is needed.

1. Open Settings → MCP servers → Add server.

2. Enter llm-subagent as the name and select STDIO.

3. Enter the command and arguments below, replacing placeholder paths with the project's actual absolute path.

4. Save, select Restart, and enter /mcp in the conversation to check server and tool status.

For file-based configuration, add this section to ~/.codex/config.toml on Windows:

[mcp_servers.llm-subagent]
command = 'C:\path\to\llm-subagent-mcp\.venv\Scripts\llm-subagent-mcp.exe'
args = ['--config', 'C:\path\to\llm-subagent-mcp\providers.toml']
tool_timeout_sec = 180

On Linux / macOS, use:

[mcp_servers.llm-subagent]
command = '/path/to/llm-subagent-mcp/.venv/bin/llm-subagent-mcp'
args = ['--config', '/path/to/llm-subagent-mcp/providers.toml']
tool_timeout_sec = 180

The client tool timeout is set to 180 seconds, exceeding the project's default 120-second upstream timeout. Use only one example; do not add the same TOML section twice. Keep API keys in the project's .env.

Example prompt after connecting:

Use llm-subagent. First call list_providers and list_models to select an available chat model. Then use delegate_task to summarize the following content, and organize the subagent's response: …

You can save the selected model ID as LLM_MODEL in .env and restart the MCP server to make it the default.

If startup fails, run the same executable with --help in a terminal and verify the --config path. If tools appear but requests fail, check LLM_API_KEY, the selected model, and provider settings. If the desktop settings entry is unavailable, check whether your app version and workspace support it. Cloud connections are described below.

ChatGPT cloud / remote clients: Streamable HTTP

For local development, start the HTTP server from the project root.

Windows PowerShell:

.\.venv\Scripts\llm-subagent-mcp.exe --config providers.toml --transport http

Linux / macOS:

./.venv/bin/llm-subagent-mcp --config providers.toml --transport http

The endpoint is http://127.0.0.1:8000/mcp. For network access, set a separate MCP_ACCESS_TOKEN in .env, start with --host 0.0.0.0, and place an HTTPS reverse proxy or protected tunnel in front of the service.

Token-based clients send Authorization: Bearer <MCP_ACCESS_TOKEN>. This is separate from LLM_API_KEY.

ChatGPT cloud connections depend on account and workspace capabilities and supported authentication flows. They require a reachable server URL or Secure MCP Tunnel for private services; they cannot directly use your computer's loopback URL. See the official custom MCP connection guide. For local desktop stdio, use the preceding section.

This version supports HTTP transport and fixed Bearer token verification, but does not implement OAuth login, token issuance, or discovery. Fixed tokens suit clients that can configure an Authorization header. If the ChatGPT connection requires OAuth, configure an OAuth gateway or FastMCP OAuth provider first. This project has not been deployed or registered with a ChatGPT account.

Validation

Windows PowerShell:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\ruff.exe check src tests

Linux / macOS:

./.venv/bin/python -m pytest -q
./.venv/bin/ruff check src tests

Tests use mocked upstream responses and do not consume RAP credits. They cover MCP tool calls, authentication headers, model selection, limits, error sanitization, and startup.

Live model access, account quotas, and full RAP response compatibility require testing with an actual RAP API key.

Official references

Documentation reviewed on November 5, 2026.

• RAP multi-model service overview: embeds the official RAP documentation.

• RAP API usage guide: https://portal.genai.nchc.org.tw/api/v1, model and chat endpoints, and x-api-key examples.

• RAP API reference: OpenAI / LiteLLM compatibility and Bearer authentication.

• FastMCP transports and token verification.

• Claude Code MCP and OpenAI MCP integration.

• ChatGPT desktop MCP configuration and ChatGPT cloud custom MCP connections.