Skip to content

5. MCP SDK Reference

📌 This page is optional, and it's for later. Everything in steps 1–4 already gave you a complete, working, deployed agent using only the UI. Come back to this page only when you're curious about talking to the platform directly through code instead of clicking buttons. If that doesn't interest you yet, feel free to stop here — you're already done!

What this is

The previous steps used the Management UI — you clicked buttons and filled in forms. Behind the scenes, that UI was calling a plain REST API (a standard way computer programs talk to each other over the web).

This page describes a second, alternative way to do the same things: the platform also exposes those same capabilities through an embedded MCP (Model Context Protocol) server. That's the same protocol you learned about in the Key Concepts section — a standard way for an agent (or another program) to connect to a service. This means an MCP-aware client — like an IDE extension, an AI agent, or another "MCP host" — can drive the platform without anyone writing REST client code by hand.

That MCP server lives in the aif.platform.management.py repo, at aif.platform.management.py/src/app/mcp_server/README.md (in the aif.platform.management.py repo — not this documentation repo), and is mounted at the /mcp path alongside the REST API. It is not a separate SDK project or a different product — it's a protocol adapter over the same service layer the REST routers in this guide call.

When would you actually use this instead of the UI?

  • You're building or configuring an MCP-compatible client (Claude Desktop, an IDE agent extension, etc.) and want it to manage agents/tools/tenants directly.
  • You want a single tool-calling interface that an LLM can use to drive its own platform administration (e.g. "create an agent for me") rather than you writing REST calls by hand.

For everything covered in steps 1–4 of this guide, the UI (as shown) is the simpler starting point. Reach for the MCP server once you have an actual MCP client you want to point at it.

Where to look

  • aif.platform.management.py/src/app/mcp_server/README.md (in the aif.platform.management.py repo) — full module map, the {domain}.{action} tool naming convention, and the list of tool modules under src/app/mcp_server/tools/ (agents, MCP servers, gateways, tenants, SOPs, audit, and more).
  • src/app/mcp_server/__init__.py — how the FastMCP app is assembled and mounted.
  • src/app/mcp_server/host_guard.py — the Host/Origin protection applied to the /mcp endpoint in production-like deployments.

Current limitations (read before relying on this in production)

The MCP facade is functionally complete but its auth posture is under active review — see aif.platform.management.py/spec/review/todo/HLD-01-mcp-facade-auth.md (in the aif.platform.management.py repo) for the authoritative tracking doc. In short: the REST endpoints used in this guide enforce the viewer/operator/admin roles described in step 1's prerequisites; the MCP tool surface does not yet enforce the equivalent per-tool role checks. Treat /mcp as a trusted-network-only surface until that HLD lands, and prefer the REST API documented in steps 1–4 for anything crossing a trust boundary today.