Expose Platform APIs to AI Assistants via an Internal MCP Server

Tier: Advanced · Hands-on time: ~2 hours

Pulumi's MCP server is the public reference for the pattern; this playbook builds yours, with read/write tiering and authz designed in from the first tool, not bolted on after the demo.

When to use

• •
  Engineers keep pasting platform state (deploy status, service catalogs, log snippets) into assistants by hand — the assistant should fetch it itself, with permissions.
• •
  You built the pb-37 action manifest and want it available inside the tools engineers already live in, instead of another chat UI.
• •
  Platform-as-a-product strategy: "works with your AI assistant" is becoming a real internal-platform feature, and you would rather ship it deliberately than have teams improvise it.

Skip MCP if only one bespoke internal app needs the integration — a direct API call is simpler. MCP pays off when multiple assistants/clients should share one governed integration point.

Prerequisites

• •
  Platform APIs worth exposing: Backstage catalog/scaffolder, deployment APIs (Argo CD, CI), observability query endpoints, or wrapped CLIs.
• •
  An MCP SDK (Python or TypeScript — both official) and familiarity with MCP basics from Common Core (tools/resources, transport, client config).
• •
  An authn story: ideally OAuth/OIDC so the server acts with the calling user's identity; minimally per-user tokens. A shared god-token is the anti-pattern this playbook exists to prevent.
• •
  pb-38's persona thinking: the MCP server is itself a governed platform workload with an identity, quotas, and audit.

The workflow

1. 1.

   Pick 3 reads and 1 gated write. Classic starter set: get_service_info (catalog metadata, owner, on-call), get_deploy_status (recent deploys, versions, health), query_logs_or_metrics (bounded, read-only query passthrough), and scaffold_service or create_ephemeral_env as the single write — approval-gated. Resist tool sprawl: assistants pick tools by description, and ten vague tools confuse models where four sharp ones excel.

2. 2.

   Design tool contracts for a model audience. Each tool gets: a description written to disambiguate ("use this for CURRENT deploy state, not history"), a tight input schema (enums for environment names, bounded time ranges, no free-form query strings where a structured filter works), and result shaping — return compact structured summaries, not 5MB JSON dumps that blow the assistant's context. Have AI draft the contracts, then edit descriptions like the product copy they are.

3. 3.

   Implement reads with identity passthrough. The server authenticates the calling user (OAuth flow or per-user token) and calls platform APIs with that identity — so existing RBAC answers "can this user see prod logs?", not the MCP server's own privileges. Log every call: user, tool, arguments, result size, latency. Rate-limit per user from day one.

4. 4.

   Implement the write as request-then-approve. The write tool does not execute — it files a validated request (pb-37's pipeline) and returns the request ID and approval link. A platform engineer (or the pipeline's policy check for sandbox tiers) approves; the assistant can poll status via a read tool. The assistant experience is still "I asked, it happened" — with a human between asking and happening for anything real.

5. 5.

   Red-team the tool surface. Injection attempts via tool arguments ("env: prod; DROP TABLE"), data exfiltration via over-broad queries, description-abuse (does the model call the write tool when a read was wanted?), and confused-deputy checks (user A cannot fetch what their RBAC denies, no matter how the assistant phrases it). Also test the reverse direction: results returned to the assistant are untrusted-adjacent too — a log line containing "ignore previous instructions" must not steer the assistant into calling the write tool; document this residual risk and mitigate with result sanitization and the approval gate.

6. 6.

   Package, distribute, and version. Ship client config snippets for your org's blessed assistants (Claude Code .mcp.json, Copilot/Cursor equivalents) via the golden-path template so onboarding is copy-paste. Version the server like an API (it is one): changelog, deprecation policy for tool signature changes, and an eval suite — canned assistant tasks ("what's deployed in staging for checkout?") that must produce correct tool calls — run in CI on every change.

Tool variants

• Python (FastMCP-style) or TypeScript SDK: equivalent capability; pick your platform team's language. Local stdio transport for laptop assistants, HTTP+SSE with OAuth for a shared deployment.
• Backstage-fronted: expose catalog + scaffolder + TechDocs search as MCP tools — composes directly with pb-36 (docs answers) and pb-35 (templates).
• Pulumi MCP server (reference): study its tool shapes for infra operations before designing yours; if you run Pulumi, it may cover the IaC slice out of the box.
• Gateway-hosted MCP: some LLM gateways can front MCP servers with added auth/rate limiting — useful when the server must serve many clients with central policy.

Verification

• •
  Eval suite green: canned tasks produce the intended tool calls with valid arguments; ambiguous requests trigger clarification, not wrong-tool calls.
• •
  Confused-deputy probe: a user without prod access gets a permission error through the assistant path, identical to the direct-API path.
• •
  Write tool provably cannot execute without an approval record; the approval link round-trip works from a real assistant session.
• •
  Audit log reconstructs a full assistant session (user, tools, arguments, results) for a sampled hour.
• •
  Injection corpus (argument-level and result-level) runs in CI; result sanitization strips known steering patterns.

Pitfalls

• The god-token server. One privileged credential serving all users is the single worst design decision available here — it converts every client-side prompt injection into platform-wide access.
• Dumping raw API responses. Huge unshaped results degrade assistant behavior and leak more data than the question needed; shape and bound every result.
• Vague tool descriptions. The description IS the routing logic for the model; ambiguous descriptions cause wrong-tool calls that no schema can catch.
• Treating it as a hackday artifact. Unversioned tool changes silently break every configured assistant in the org; it is an API with an SLA the moment two teams use it.
• Forgetting result-side injection. Logs, ticket text, and doc content flow back through your server into the model — sanitize, and keep the write path approval-gated precisely because reads can be poisoned.

Restricted-environment variant

• •
  Self-host the full path for client estates: assistants configured against client-approved models (Bedrock/Azure OpenAI private, or Ollama/vLLM via LiteLLM), MCP server deployed inside the client boundary, logs retained per MSA. The MCP server makes client-safe AI MORE achievable: engineers stop pasting client state into arbitrary tools because the governed path is the convenient one.
• •
  Per-engagement servers (or per-engagement tool allowlists) so client A's platform is unreachable from client B's context — mirror pb-36's corpus separation.
• •
  Free-tier lab path: stdio-transport MCP server + a local assistant + kind cluster reproduces everything, including the approval-gated write, at ₹0.

Success criteria

• •
  Engineers' assistants answer platform questions via governed tool calls — measured drop in state-pasting and credential sharing.
• •
  One write path live with a working approval loop and zero ungated executions in the logs.
• •
  The eval + injection suites run in CI, and a deliberate breaking tool change is caught before release.
• •
  A second team adopts the server via the packaged config within a month — proof it is a platform capability, not a demo.