Expose Your Platform to AI Assistants: An Internal MCP Server with Authz Tiers

Tier: Advanced · Workflow area: Agent operations & guardrails

This playbook wraps your IDP's capabilities — service catalog, deployments, logs, golden-path scaffolding — as an MCP server with read/write tiering, per-agent identity, quotas, and an audit trail, so the platform's paved road extends to AI callers under the same governance as human ones. Pulumi's MCP server is the public reference for the pattern; here you build it for your own platform APIs.

When to use

• •
  Engineers already paste platform data into assistants by hand — the demand exists; only the safe path is missing.
• •
  You run an IDP (Backstage or equivalent APIs) and want agents as a supported persona with RBAC, quotas, and audit, not a shadow integration.
• •
  pb-49/pb-50 gave you action tiers and sandboxes; this is the curated tool surface that agents should prefer over raw shell access.

Skip a custom server where a mature vendor MCP server already covers the tool (GitHub, Pulumi, your cloud) — wrap only what's yours: the platform's own APIs.

Prerequisites

• •
  Platform capabilities already behind HTTP APIs (Backstage catalog, deploy service, log query) — MCP wraps APIs; it doesn't replace them.
• •
  MCP SDK: Python (mcp package, stable v1.x — examples below; note the v2 beta line renames FastMCP to MCPServer, so pin v1 or adjust) or TypeScript.
• •
  An OAuth/OIDC-capable identity provider — the MCP spec's HTTP auth model treats your server as an OAuth resource server.
• •
  The pb-49 blast-radius ladder: it becomes this server's tool tiering.

The workflow

1. 1.

   Choose the first tools by tier: three reads, one gated write.

   Tool	Tier	Backing API
   get_service(name)	read	catalog API
   list_deployments(service, env)	read	CD API
   fetch_logs(service, env, minutes)	read	log API (result-size capped)
   create_service(name, template, owner)	write, approval-gated	scaffolder API

   Reads make the server immediately useful; the single write proves the governance path end-to-end.

2. 2.

   Build the server with tools as typed functions.

   Copy

   from mcp.server.fastmcp import FastMCP
   
   mcp = FastMCP("platform")
   
   @mcp.tool()
   def get_service(name: str) -> dict:
       """Fetch a service's catalog entry: owner, tier, on-call, links."""
       return catalog.get(name)          # calls the real platform API
   
   @mcp.tool()
   def create_service(name: str, template: str, owner: str) -> dict:
       """Scaffold a new service via the golden path. Requires approval."""
       return scaffolder.request(name, template, owner, requested_by=current_caller())
   
   mcp.run(transport="streamable-http")
   

   Docstrings and type hints become the tool schema the model sees — write them prescriptively ("call this when...") since they steer tool selection. Keep results small and structured; a tool that returns 50k log lines blows the caller's context and your egress.

3. 3.

   Authenticate callers, then tier them. Front the server with OAuth (spec-standard for HTTP transport): every caller — a human's assistant or a headless agent — presents a token tied to an identity. Map scopes to tiers: platform.read unlocks the read tools; platform.write additionally unlocks gated writes. Enforce in the server (check scope per tool call), not in documentation. Headless agents get their own service identities — never a borrowed human token — so RBAC, quota, and audit distinguish "Priya's assistant" from "the nightly triage agent."

4. 4.

   Gate the write with a human approval. create_service does not scaffold directly: it files an approval (platform ticket or Slack flow) carrying the caller identity and full arguments; a platform engineer approves; the scaffolder runs; the tool returns the request status either way. This is pb-49's approval tier implemented at the tool boundary — the agent experiences it as an async tool, not a denial.

5. 5.

   Quota and rate-limit per identity. Agents retry enthusiastically; a misconfigured one is a DoS with a personality. Apply per-identity rate limits at your API gateway in front of the MCP server, plus per-tool budgets for expensive calls (fetch_logs). Return structured "quota exceeded, retry after" errors — models handle them well when they're explicit.

6. 6.

   Audit every call, then run the acceptance drill. Log caller identity, tool, arguments, decision (allowed/denied/approval-pending), and result size — to the same SIEM/dashboards as pb-49/pb-50 (join on identity). Drill: connect an approved assistant, exercise all four tools; verify a read-scoped identity is denied the write; verify the write pauses for approval and the audit log reconstructs the whole session; verify a token with no scopes gets nothing.

Tool variants

• Python mcp SDK v1 / FastMCP (this playbook): fastest path; TypeScript SDK equivalent if your platform tooling is Node.
• Pulumi MCP server: the public reference implementation to study for shape and scope decisions before writing your own.
• Backstage MCP plugins: emerging ecosystem — evaluate before hand-wrapping catalog APIs, but hold them to this playbook's authz bar.
• API-gateway-fronted deployment: run the server behind your existing gateway (Kong/Envoy) to reuse OAuth introspection, rate limiting, and WAF instead of rebuilding them.

Verification

• •
  Tier test matrix passes: read identity → reads work, write denied; write identity → write files approval; no scopes → all denied. Kept as a repeatable script.
• •
  Approval round-trip works and both approve and reject paths return coherent tool results.
• •
  Rate-limit test: a looping client is throttled with a structured error and the platform APIs behind stay healthy.
• •
  Audit log for a full session reconstructs every call with identity and arguments; security has reviewed the log schema.

Pitfalls

• Wrapping raw power instead of the paved road. An MCP tool that executes arbitrary kubectl is a remote shell with a schema. Tools expose intents (scale service X within bounds), the same golden paths humans get.
• Trusting client-side tool choice as authz. The model choosing not to call a tool is not access control — the server enforces scopes on every call regardless of what the client claims.
• One shared "agent" identity. Kills attribution, quotas, and revocation in one stroke. Identity-per-agent is non-negotiable.
• Unbounded tool output. Log and catalog dumps flood model context and leak more than intended — cap, paginate, and summarize server-side.
• SDK version drift. The MCP spec and SDKs move fast (v2 renames core classes); pin versions and re-run the acceptance drill on upgrade.

Restricted-environment variant

• •
  Run the MCP server inside the platform's (or client's) boundary; it is another internal API, not a SaaS hop. Assistants that may connect to it are only those on the org's approved list — enforce at the OAuth client-registration level.
• •
  For client engagements, scope a dedicated server instance to the engagement's systems with the client's identity provider; tool results containing client data inherit the client's data-handling rules (redaction per pb-49 where responses transit hosted models).
• •
  Air-gapped: MCP works fully offline with in-boundary assistants/models (pb-43 stack) — no component requires internet.

Success criteria

• •
  An org-approved assistant answers real platform questions (owner, deploy status, recent logs) through governed tools instead of pasted screenshots.
• •
  The first agent-initiated service scaffold shipped through the approval gate with a complete audit trail.
• •
  Per-identity usage shows up in pb-46 dashboards beside model spend — agents are visible tenants.
• •
  New platform capabilities get an MCP tool + tier decision as part of definition-of-done, the same way they get docs.