Stores definitions for all executor agent types and exposes them via an MCP server.
514
Internal forfetch.ai agent type registry. Stores definitions for all executor agent types and exposes them via an MCP server. Single source of truth for what agents exist, what they can do, how to deploy them, and how much they cost.
Used by planning agents (plan_self_ask_agent, plan_judge_agent) to discover available executors, and by the orchestrator and K8s tooling to look up images, ports, and resource requirements.
app/seed.py into PostgreSQL./.well-known/agent.json from a running pod and caches it in the DB.| Key | Type | Skills |
|---|---|---|
linux_chrome_agent | one_time | navigate, click, double_click, type, scroll, screenshot, extract_text, evaluate_js, hover, select_option |
linux_gui_agent | one_time | take_screenshot, click, double_click, type, scroll, key_press, mouse_move |
antidetect_browser_agent | one_time | navigate, click, double_click, type, scroll, screenshot, extract_text, evaluate_js |
android_agent | one_time | tap, swipe, type, screenshot, back, home, launch_app, scroll |
linux_terminal_agent | one_time | run_command, write_file, read_file, list_dir, install_package |
downloader_agent | one_time | download_file, list_downloads, get_download_status |
orchestrator_agent | persistent | orchestrate |
plan_self_ask_agent | one_time | plan |
plan_judge_agent | one_time | plan |
schedule_agent | persistent | schedule |
app/
config.py pydantic-settings configuration
db.py build_engine() + build_session_factory()
models.py SQLAlchemy ORM — AgentTypeRow
schemas.py Pydantic response schemas
catalog_service.py query layer (no MCP/FastAPI imports)
seed.py hardcoded agent definitions — single source of truth
mcp_server.py FastMCP server + lifespan + 3 tools
cli.py typer CLI: seed / serve / refresh-card
alembic/ database migrations
cp .env.example .env
docker compose up
This starts PostgreSQL, applies migrations, and launches the MCP server on port 8001 (streamable-http transport).
Seed agent definitions after first start:
docker compose run --rm app agents-mcp seed
docker run --rm -i \
-e AGENTS_MCP_DATABASE_URL=postgresql+psycopg://agents_mcp:agents_mcp@host:5432/agents_mcp \
agents-mcp
The default CMD is agents-mcp serve --transport stdio, suitable for direct use with MCP clients.
cp .env.example .env
| Variable | Required | Description |
|---|---|---|
AGENTS_MCP_DATABASE_URL | yes | PostgreSQL connection string |
AGENTS_MCP_HOST | no | Bind address for streamable-http mode (default 0.0.0.0) |
AGENTS_MCP_PORT | no | Port for streamable-http mode (default 8001) |
LOG_LEVEL | no | DEBUG, INFO, WARNING, or ERROR (default INFO) |
uv sync
docker compose up -d postgres
Or create the database manually on an existing instance:
CREATE USER agents_mcp WITH PASSWORD 'agents_mcp';
CREATE DATABASE agents_mcp OWNER agents_mcp;
uv run alembic upgrade head
uv run agents-mcp seed
Expected output:
Seeding agent_types...
inserted linux_chrome_agent
inserted linux_gui_agent
inserted antidetect_browser_agent
inserted android_agent
inserted linux_terminal_agent
inserted downloader_agent
inserted orchestrator_agent
inserted plan_self_ask_agent
inserted plan_judge_agent
inserted schedule_agent
Done. (10 agents)
Re-running seed is safe — it upserts, so existing rows are updated and no duplicates are created.
stdio transport (for Claude Desktop or other MCP clients):
uv run agents-mcp serve --transport stdio
HTTP transport:
uv run agents-mcp serve --transport streamable-http
# or override host/port:
uv run agents-mcp serve --transport streamable-http --host 127.0.0.1 --port 8001
Fetch /.well-known/agent.json from a running pod and cache it in the DB:
uv run agents-mcp refresh-card --key linux_chrome_agent --url https://pod.local:443
agents-mcp seed
Upsert all agent definitions from seed.py into the database.
agents-mcp serve
Start the MCP server.
--transport stdio | streamable-http (default: stdio)
--host TEXT Override bind host (streamable-http only)
--port INT Override bind port (streamable-http only)
agents-mcp refresh-card
Fetch /.well-known/agent.json from a running pod and cache it in the DB.
--key TEXT Agent type key, e.g. linux_chrome_agent (required)
--url TEXT Base URL of the running pod (required)
| Tool | Description |
|---|---|
list_agent_types | List all agent types. Filterable by type_of_instance and enabled_only. Returns AgentSummary (key, name, description, type_of_instance, skills, required_env, price_per_turn). |
get_agent_type | Full details for a single agent type by key. Returns AgentDetail (adds image, ports, resources, pricing, cached card). |
get_agents_for_planning | Returns agent definitions in AgentForPlanning format — the schema expected by plan_self_ask_agent and plan_judge_agent as their available_agents input. The url field is a logical placeholder (agent-type://{key}); replace with actual instance URLs before passing to planners. |
AgentForPlanning schema{
"name": "Linux Chrome Agent",
"url": "agent-type://linux_chrome_agent",
"description": "Browser automation via Chrome CDP + VLM...",
"type_of_instance": "one_time",
"price_per_turn": 0.00625,
"skills": [
{"id": "navigate", "name": "Navigate", "description": "Navigate the browser to a URL"},
{"id": "click", "name": "Click", "description": "Click on an element or coordinates"},
...
]
}
price_per_turn is derived from pricing["llm_cost_per_turn"]["gpt-4o"] at seed time using the following rates:
| Cost component | Rate |
|---|---|
| LLM input tokens | $2.50 / 1M (GPT-4o) |
| LLM output tokens | $10.00 / 1M (GPT-4o) |
| Infrastructure (CPU) | $0.048 / vCPU / hour |
| Infrastructure (memory) | $0.006 / GB / hour |
The full pricing dict on AgentDetail also includes claude-sonnet-4-6 rates, infra cost per turn, startup cost per job, and usage notes.
Lint:
uv run ruff check app
uv run ruff format --check app
Generate a new migration after changing models:
uv run alembic revision --autogenerate -m "describe the change"
uv run alembic upgrade head
Content type
Image
Digest
sha256:411b39262…
Size
83.7 MB
Last updated
5 months ago
docker pull superbizon007/agents-mcp