api_agent_mcp

An MCP server for reusable, role-based agents. It supports Solo mode and bounded Discussion mode: independent proposals, parallel critique, a separate judge, optional revision rounds, and SQLite session events.

See dsaa.md for the original project vision and architecture notes (Russian).

Quick start

uv sync --extra test
export API_AGENT_API_KEY="your-provider-key"
# Optional: OpenAI-compatible endpoint and default model
export API_AGENT_BASE_URL="https://api.openai.com/v1"
export API_AGENT_MODEL="gpt-4o-mini"
uv run api-agent-mcp

The server uses stdio transport. Set API_AGENT_DB to override the database path; the default is ~/.api_agent_mcp/data.db. Task text and model responses are stored in the local SQLite event log, so protect or remove that database if it contains sensitive data.

• API_AGENT_TIMEOUT: provider request timeout in seconds (default 120)

Related MCP server: tatwo-ultrawork-beta

MCP tools

• create_agent: add a profile with a name, role, system prompt, optional model and routing tags.

• update_agent: update provided profile fields.

• list_agents: list configured profiles.

• run_solo: run a task with a named agent, or route by matching tags. Ambiguous/no matches return an error instead of silently choosing the wrong profile.

• run_discussion: start independent proposals, collect parallel critiques, ask an independent judge for a structured verdict, and revise if the judge reports no consensus.

Profiles are also exposed as agent://profiles/{name} resources.

Discussion requires at least two distinct participant profiles and a separate judge profile (pass judge, or register a profile with role judge). It runs synchronously over MCP stdio and reports progress when the client supports it. Limits: 2–5 participants, 1–5 rounds; the shared max_output_tokens budget must allow at least 64 tokens per worst-case model call. Subagent spawning and resumable background execution are not implemented yet.

run_solo.max_output_tokens limits the requested generated output. Provider-reported completion-token usage is logged. run_discussion.max_output_tokens is a shared completion-token budget reserved across concurrent calls; providers that omit usage are charged the full reservation. This is not a dollar-cost limit and excludes prompt/input tokens.

Provider support

The client uses /chat/completions on an OpenAI-compatible API. Configure the provider endpoint with API_AGENT_BASE_URL; the API key is read from API_AGENT_API_KEY. Secrets are not stored in profile records.

Development

uv sync --extra test
uv run pytest

Roadmap

1. Solo mode and profile registry

2. Bounded Discussion with independent proposals, critics, judge, blackboard, and output-token budget (current)

3. Subagent verification and resumable background execution for long-running discussions