Building MCP Tools for Internal Platforms

The Problem#

Internal platforms are full of useful actions: deploy a service, create an incident, query a runbook, toggle a feature flag, or inspect logs. AI assistants can help, but only if these actions are exposed safely.

Why It Matters#

MCP gives platform teams a standard way to publish tools to AI clients. Good tool design can reduce context switching. Bad tool design can create a dangerous remote control for production.

Core Concepts#

Design tools around user intent, not backend implementation. A tool should have a small schema, a clear permission boundary, predictable output, and a risk level. For write actions, provide preview and execute phases.

Implementation#

Split risky work into two tools:

preview_deploy(service, environment, version)
execute_deploy(deploy_plan_id, approval_token)

The preview tool validates inputs and returns the exact action plan. The execute tool accepts only a generated plan id and approval token.

Example#

A developer asks an assistant:

Deploy catalog-api version 9f31c2a to staging.

The assistant should first call:

{
  "tool": "preview_deploy",
  "args": {
    "service": "catalog-api",
    "environment": "staging",
    "version": "9f31c2a"
  }
}

The tool returns:

{
  "deployPlanId": "dep_123",
  "changes": ["update image tag", "run smoke tests", "notify #catalog"],
  "requiresApproval": false
}

Only then should the assistant call execute_deploy with dep_123. For production, the same preview could return requiresApproval: true and block until the human approves the exact plan.

Common Mistakes#

• Exposing one generic admin tool.
• Returning raw logs when summarized structured fields are enough.
• Letting the model choose production by default.
• Skipping dry-run support for deployments and feature flags.

Production Considerations#

Start with read-only tools: service ownership, runbook lookup, deployment history, incident status, and feature flag state. Add writes only after audit, approval, and rollback paths are mature.

Security#

Bind every tool call to the human user identity. Service accounts should execute the action, but the audit trail must show who requested it.

Performance#

Tools should return compact responses. For logs and traces, return links or summaries first, then fetch details only when the user asks.

Summary#

MCP is a strong fit for internal developer platforms when tools are narrow, permissioned, auditable, and designed around safe operational workflows.