MCP interface — expose the domain to AI agents as choreography participants

[matt-beanland]

Description

Add a Model Context Protocol (MCP) interface to diffo_example so AI agents (Claude, GPT, local models) can read from and act on the domain directly — and, more interestingly, participate in the choreography we've been yarning about.

The standard story for MCP is "AI as a query layer" — let the assistant fetch data and call tools. That's table stakes. The deeper story is AI as a Party — declaring its preferences (or its principal's), bringing up its own value characteristics, yarning with other parties to align on best, taking one for the team when the ledger asks.

Three layers of MCP integration

1. Read surface — the domain as queryable.
MCP resources/tools that wrap the natural domain reads: list instances, get by id, run feasibility queries (#38, #39), find by note relevance (#43). The aspect-family answers (#41) and the value-with-collapse-function shape (#42) translate naturally to MCP responses — the AI can ask the simple form or the rich form depending on what it needs to reason about.

2. Write surface — the domain as actionable.
MCP tools that wrap the action surface: build/define/relate/assign. With the actor-based multi-tenancy from RSP (#36), the AI inherits the principal's authority — it can do what its principal can do, no more.

3. Participation surface — the AI as a Party in choreography.
This is the interesting one. The AI is a Party with its own (or its principal's) preferences. It brings up its value functions like any other party. It receives feasible sets, computes its preferred options under its worldview, yarns with other parties (via natural-language back-and-forth that becomes Notes on the relevant instances per #43), defers when the ledger asks, advocates when it's its turn. The choreography stays the same; the AI is just another dancer.

Why it matters

MCP is the standard way to give AI agents domain access today. Without it, every consumer rebuilds the same wrapper. With it, diffo_example demonstrates not just "AI can query our domain" but "AI participates in the same choreography as any other party — with the same agency, the same constraints, the same honest answers (aspect family), the same ledger."

It also tests the agency story honestly. If the domain primitives — bring up, expect, align, yarn — are real and well-shaped, AI should be able to use them as cleanly as any human-driven consumer. If we have to bolt on AI-specific affordances, the primitives weren't quite right.

And the worldview-as-configuration dream (#40, #41, #42) gets a real test: can an AI agent be configured with a worldview at session start, then make consistent decisions across an interaction? Can two AI agents with different worldviews yarn to a settlement? Honest test of whether the structural ethics actually operate.

A possible direction

Ash has emerging MCP affordances (or close enough) that we can plug into. Two layers of work:

• Mechanical wrapping of the existing read/write actions as MCP tools. Probably mostly generated from the code_interface declarations and action signatures. Should be small once the patterns are settled.
• Choreography-shaped tools — higher-level tools that compose the primitives in choreography form: propose_option, defer_for_team, record_yarn_note, align_preferences. These are the AI-as-participant surface, and shape themselves into the same primitives the rest of the domain uses.

The exemplar work would be:

1. Wire one Access action through MCP (probably qualify_dsl since it's the natural entry point) to prove the round-trip.
2. Then add the semantic-note search (#43) as an MCP tool — natural language → relevant instances is the canonical AI query.
3. Then prototype an AI-as-Party scenario — two parties with different worldview configurations yarn to settle on an option, and the yarn itself lands as Notes on the relevant instances.

Related:

• Everything else open — MCP is the surface through which all of it becomes accessible to AI agents. It's the integration layer that proves the dream is real.

[matt-beanland]

Sharper framing — MCP isn't an alternative to TMF641/640, it's a better-fit interface for reasoning agents. Two consumer classes, two surfaces, same domain underneath:

• Operational systems (legacy B/OSS, partner OSS, orchestrators) → TMF641/640/638 HTTP APIs. JSON-Schema-bound payloads, RFC 7396 merge-patch, polling and notification hooks. The conventions exist to placate REST/HTTP norms that those systems need to interop. Hoop-jumping for the consumers who require it.
• Reasoning agents (AI, MCP clients, anyone composing rich queries with intent) → MCP. Typed tools, structured responses, conversation, the aspect family (#41) and value-with-collapse-function (#42) as native return shapes. No JSON-merge gymnastics, no schema-policed envelopes — the consumer holds the context and asks at the right level of richness.

Same domain primitives underneath. The choreography, value metrics, feasibility, expectations don't care which surface called them. The cost of each surface is paid only by the consumers who need it.

That also frees us to not implement TMF641/640 round-trips for the AI path. If a reasoning agent wants to propose, yarn, defer — it does that natively through MCP. Operational systems can poll a TMF641 endpoint later if/when one is needed for actual partner-OSS interop. The reasoning surface isn't gated by anything the operational surface decides.

Reframed: MCP is the front door for reasoning. TMF HTTP APIs (when we eventually need them) are the side door for legacy interop. Same house.

[matt-beanland]

Refining the surface boundaries:

• Jettison TMF641 / TMF640 — service ordering and activation/configuration. These are the process / orchestration APIs with merge-patch, polling, notification-callback machinery. They exist to make TMF orchestrators happy. They are the bother. Reasoning agents and the choreography pattern make them redundant — the same intent expressed cleanly through MCP tools or directly against the domain.

• Keep TMF638 / TMF639 as required projection — service inventory and resource inventory. These are the state-shape APIs — how TMF-aware consumers expect to see what exists. They're a bridge to the TMF world, not orchestration machinery. They're the lossy collapse from our richer domain into the TMF inventory format (exactly the projection from diffo#169 — TMF638 effectively is the Provider domain's natural JSON projection).

So three consumer surfaces total:

1. MCP — for reasoning agents. Native richness, conversation, the aspect family and value-with-collapse-function shapes (#41, #42).
2. TMF638 / TMF639 inventory — for TMF-aware consumers who need to see state. A collapse from our domain into the TMF JSON shape — the explicit, named projection we yarned about in diffo#169. Read-mostly.
3. (Maybe later) partner integrations — bespoke surfaces only when a specific partner-OSS actually requires one. Not by default, not for everyone.

Notably absent: TMF641/640. Their orchestration vocabulary is what the choreography pattern replaces. Process-as-payload-shape vs process-as-emergent-alignment — different worlds, no need to bridge.

[matt-beanland]

Done as of 9458770 mcp on 44-mcp-interface. ash_ai made the minimum viable path very small — about 30 lines of changes across mix.exs, the two domains, and the existing Nbn router.

What landed:

• {:ash_ai, "~> 0.6"} added. Pulled req out of only: [:dev, :test] because llm_db (a transitive dep) needs it at runtime.
• tools do ... end block on both DiffoExample.Access and DiffoExample.Nbn declaring every domain action as an MCP tool. 60 tools total — 23 in Access (DslAccess qualify/result/design, Shelf/Card/Cable/Path build/define/relate/assign/read) and 37 in Nbn (NbnEthernet/Uni/Avc/Ntd/Cvc/NniGroup/Nni build/define/relate/assign/read + Rsp inventory/build/activate/suspend/deactivate).
• forward "/mcp" to AshAi.Mcp.Router from DiffoExample.Nbn.Router (the existing Plug.Cowboy app on port 4000), with tools: true, otp_app: :diffo_example, protocol_version_statement: "2024-11-05".
• 48/48 tests still green.

Round-trip verified with curl:

# initialize
curl -sS -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
  http://localhost:4000/mcp
# → server identifies, capabilities

# tools/list
curl -sS -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}' \
  http://localhost:4000/mcp
# → 60 tools, each with JSON Schema

# tools/call
curl -sS -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"list_rsps","arguments":{}}}' \
  http://localhost:4000/mcp
# → list of 6 seeded RSPs returned through the protocol

What the discipline gave us for free:

The AI surface inherits everything the domain already enforces — RSP-actor multi-tenancy, the relationships do permitted_source_roles, the Define/Relate/Assign change modules, the resource_state lifecycle gate on the Assigner, the BaseInstance fragment polymorphism. We wrote zero AI-specific business logic. Zach's "tool calling via existing actions" framing in the Ash AI blog maps exactly: authorization is compositional, not bolted-on; the AI is just another consumer with the same constraints.

What's intentionally absent (and noted in the comment thread):

• Party/Place creation (Diffo.Provider.create_party, Diffo.Provider.create_place) — not exposed. Provider primitives are deliberately not surfaced through Access/Nbn MCP. The plan: once Access/Nbn have their own domain APIs for creating party/place relationships, those go in tools do and get the same authorisation treatment. RSP actors won't have full authorisation; NBN internal actors will. Same surface, authorisation as the dimension.
• TMF641/640 — not on the roadmap. The choreography pattern replaces orchestration-as-payload-shape. TMF638/639 inventory remains the bridge to TMF-aware consumers (per diffo#169).
• Auth on the MCP route — no AshAuthentication.Strategy.ApiKey.Plug yet. Local-dev use case for now; production wiring is straightforward when needed.

Side benefit surfaced by the work:

For domains that want to ingest from legacy databases, the pattern is ingestion via reasoning, not ETL. Wire an AI agent to both legacy DB tools (Postgres/MSSQL/REST MCP connectors) AND this MCP server. The agent reads legacy, translates, calls the discipline-enforced tools to populate the clean domain. No schema mappers, no transformation pipelines, no coupling adapters. The clean domain stays sovereign over its own integrity; the AI is the translation layer; the translation lives in the agent's reasoning, not in our code.

[matt-beanland]

Setup guide added: documentation/how_to/setup_mcp.md.

Covers:

• Prerequisites and starting the server
• Verifying MCP is up with curl (initialize, tools/list, tools/call)
• Wiring Claude Code (claude mcp add diffo --transport http http://localhost:4000/mcp)
• Wiring Claude Desktop (claude_desktop_config.json HTTP entry)
• Pointing other MCP clients (Cursor, Continue, custom) at it
• The current tool surface (~23 Access + ~37 Nbn, listed by group)
• Adjusting the surface (tools: true → explicit list for narrower scopes)
• Adding new tools — references AGENTS.md for the keep-aligned convention
• Authorisation notes (unauthenticated local-dev; how to wire AshAuthentication.Strategy.ApiKey.Plug for production multi-tenancy)
• Troubleshooting (zero tools, connection refused, policy errors, schema mismatches)

Registered in mix.exs under "How To" so ex_doc picks it up alongside the existing NBN livebook and domain docs.

Also added AGENTS.md at the repo root capturing the discipline for keeping the tools do blocks aligned with the define-d actions — the compile doesn't catch a missing tool entry, so it's worth a written reminder for future Claudes / Cursors / humans working in the repo.