agensflow-mcp 0.1.0

AgensFlow MCP — learned coordination substrate for coding-agent loops

agensflow-mcp

Learned coordination substrate for coding-agent and MAS loops. Apache-2.0. Self-host, or use the hosted service.

What this is

AgensFlow MCP is a policy server. For each task signature your agent sees, it learns which sub-agent, model, and effort setting produces the best outcome — where "best" is a weighted trade-off of quality, cost, latency, and token budget you configure.

Under the hood: a per-signature UCB1 bandit with Welford-online variance, Anthropic cache-aware pricing, tenant isolation, and BYOK judge orchestration.

Two integration paths cover essentially every agent shape:

• Framework adapters — LangGraph, CrewAI, or any Runnable-shaped MAS framework plug in via agensflow-langgraph: one decorator per node, per-node model pool, one line to record reward. The adapter owns judge orchestration; the server records decisions and updates the policy.
• Direct MCP integration — Claude Code / codex hook the server via PreToolUse + SubagentStop hooks. The server orchestrates a BYOK single-model or 3-panel cross-family judge over POST /judge/relative.

Install

pip install agensflow-mcp

Requires Python ≥ 3.11. Postgres is recommended for production; SQLite works out-of-the-box for local dev.

Run the server

# Local dev (in-process SQLite, no external deps)
agensflow-mcp serve
# → http://localhost:8000/health
# → http://localhost:8000/docs      (OpenAPI schema explorer)
# → http://localhost:8000/mcp/sse   (FastMCP endpoint)

# Full stack with Postgres via Docker
docker run -d --name agensflow-postgres \
  -e POSTGRES_PASSWORD=agf -p 5432:5432 postgres:16
AGF_DATABASE_URL=postgresql+psycopg://postgres:agf@localhost:5432/agensflow \
  agensflow-mcp serve

Once up, verify:

curl -s http://localhost:8000/health
# → {"status":"ok","version":"..."}

Architecture

      Framework                Claude Code
      adapter                  / codex hooks
     (LangGraph, CrewAI, ...)      │
        │                          │
        └─────────┬────────────────┘
                  ▼
         ┌──────────────────────────────────────────┐
         │ HTTP + MCP surface                       │
         │                                          │
         │  /route            /judge/relative       │
         │  /record           /policy/{me,id}       │
         │  /auth/anonymous   /auth/byok            │
         │  /langgraph/policy/{select,import,       │
         │                     export}              │
         │  /langgraph/decision/execute             │
         │  /langgraph/reward/submit                │
         │  /langgraph/decisions                    │
         │                                          │
         │  /mcp/sse           (FastMCP tools)      │
         └────────────────────┬─────────────────────┘
                              ▼
                    ┌───────────────────┐
                    │ Substrate engine  │
                    │   folding · UCB1  │
                    │   Welford         │
                    │   reward · pricing│
                    └─────────┬─────────┘
                              ▼
                     Postgres / SQLite

Tier model

Tier	Package	What you get
Free	agensflow-mcp (public, PyPI)	UCB1 substrate, reward formula w_q·quality − w_c·cost − w_t·tokens − w_l·latency, tenant isolation, all HTTP endpoints (/route, /record, /judge/relative, /langgraph/*, /auth/*, /policy/*), 3-judge cross-family panel over OpenRouter (BYOK), extension plugin discovery for overlays
Enterprise	Private overlay (not on PyPI)	Everything above + private-tier observability signals and reward extensions. Auto-loaded via importlib entry-point when installed

The free tier is fully functional standalone. Enterprise is an overlay you install alongside; the server auto-discovers it at boot and mounts the additional routes + companion tables. Nothing on the free tier depends on the enterprise package being present.

Learn more

• Integration guide (LangGraph adapter) — agensflow-langgraph docs
• API reference — boot the server and open http://localhost:8000/docs
• Privacy & data handling — PRIVACY.md
• Self-hosted deployment — DEPLOY.md

License

Apache-2.0