ietf-draft-analyzer/workspace/docs/poc-mcp-langgraph-plan.md

PoC Plan — ACT + ECT over MCP with LangGraph

Target: end-to-end working demo for IETF 123 preparation and draft credibility. Location: demo/act-ect-mcp/ (moved out of workspace/poc/ to be a first-class peer of paper/ and workspace/) Date: 2026-04-12

Scenario

A user issues a mandate (ACT authorization token) to a LangGraph agent: "research topic X, produce summary." The agent, running in a LangGraph StateGraph, calls two tools exposed by an MCP server:

1. search(query) — returns fake hits
2. summarize(text) — returns fake summary

Every MCP tool call is authenticated by:

• ACT mandate in Authorization: Bearer <act-jwt> header (capability check: cap=["mcp.search","mcp.summarize"])
• ECT execution context in a signed HTTP header per draft-ietf-wimse-http-signature-03 using the wimse-aud signature parameter
• Tool-call body hashed into ECT inp_hash

On tool success, the agent mints an ACT execution record with:

• status="completed"
• pred=[mandate.jti] for the first call, pred=[mandate.jti, prev_exec.jti] for subsequent calls (DAG, not linear)
• inp_hash / out_hash bound to request/response bodies

A standalone verify CLI walks the resulting ACT ledger + ECT store and prints the DAG.

Components

poc/mcp-langgraph/
├── README.md                 # how to run, what it proves
├── pyproject.toml            # depends on ietf-act, ietf-ect, mcp, langgraph, fastapi
├── keys/                     # generated ES256 keys (gitignored)
├── src/
│   ├── keys.py               # key gen + JWKS loader
│   ├── tokens.py             # ACT mandate/exec minters, ECT header builder
│   ├── http_sig.py           # minimal http-signature-03 signer/verifier
│   ├── server.py             # MCP server (FastMCP streamable-http) + ECT/ACT middleware
│   ├── agent.py              # LangGraph agent + MCP client, injects ACT+ECT
│   └── verify_cli.py         # walks ledger, prints DAG
├── demo.sh                   # end-to-end: start server, run agent, run verifier
└── tests/
    ├── test_token_flow.py    # one tool call → one exec record linked via pred
    └── test_dag_shape.py     # two tool calls → DAG with expected pred edges

Build sequence (verifiable increments)

1. Skeleton + deps: pyproject.toml, package layout, install works.
2. Keys + tokens: keys.py, tokens.py. Unit test: mint mandate, mint exec, verify both.
3. HTTP signature: http_sig.py. Unit test: sign request, verify (round-trip).
4. MCP server: FastMCP with two fake tools + ASGI middleware that verifies ACT+ECT on every call. Manual curl test.
5. LangGraph agent: StateGraph, langchain-mcp-adapters with custom headers callback. No LLM — scripted node sequence that calls both tools.
6. Verifier CLI: prints the DAG (mandate → exec1 → exec2).
7. End-to-end demo.sh: spawns server, runs agent, runs verifier. Green = PoC done.

Explicit non-goals

• Real LLM via Ollama (local, zero API cost). create_react_agent decides which MCP tools to call. Token flow is deterministic regardless of LLM output.
• No registration / discovery of agents — assume pre-shared JWKS.
• No distributed SCITT anchoring — in-memory ledger only.
• No Go interop in this PoC (Python + Python). Go path tracked separately.

Tradeoffs

Real MCP vs. MCP-shaped: use real MCP SDK (FastMCP server + streamablehttp_client). More credible for IETF reviewers; adds dep weight. If the MCP SDK blocks us from injecting ECT on the HTTP layer, fall back to FastAPI endpoints that mirror the MCP JSON-RPC shape.

LLM: real. Ollama qwen3:8b as default (local, free, reproducible per CLAUDE.md cost policy). Swap to Anthropic/OpenAI via env var. LangGraph create_react_agent wires LLM + MCP tools.

Success criteria

• demo.sh exits 0, verifier prints a DAG with 1 mandate + 2 execs + correct pred edges.
• All unit tests green.
• README shows a reviewer can reproduce in under 5 minutes (uv sync && ./demo.sh).

Questions before coding

• OK to put PoC under workspace/poc/mcp-langgraph/ (new dir), not under packages/?
• OK to pin mcp>=1.0, langgraph>=0.2, langchain-mcp-adapters as deps?
• LangGraph without an LLM is fine for v1 of the PoC, right?