Skip to content
managed.devdocs

MCP server

Preview The official Model Context Protocol server puts the managed.dev API in front of an AI agent as a set of typed tools. It runs over the SDK, so it inherits the same scopes, jobs, and capability discovery — an agent gets exactly the surface your key grants it and nothing more.

why the API is already agent-native

Section titled “why the API is already agent-native”

The design choices that make the API pleasant for humans are the same ones that make it safe for agents — this isn’t a separate “AI mode” bolted on:

Scope-bounded

A tool can’t exceed the key’s scopes. Hand an agent a read-only-plus-wp.cli:exec key and it physically cannot delete a site, rotate a credential, or mint another key — those scopes aren’t on the token.

Idempotent

Action tools attach an Idempotency-Key, so an agent that retries (they do) replays the original job instead of running the action twice.

Job-returning

Mutations return a job the agent can poll for a real outcome, instead of a fire-and-forget call it can’t verify.

Capability-typed

The agent asks a site what it can do rather than guessing — no hallucinated wp plugin call against a static site.

what the server exposes

Section titled “what the server exposes”

Tools fall into two tiers, mapped to scopes so you grant only what a given agent needs:

  • Read tools — get_site, list_sites, get_capabilities, get_insights, get_logs, get_security_blocks, get_job. These need only *:read scopes and are safe to hand any agent.
  • Narrowly-scoped action tools — exec_command (gated by wp.cli:exec), update_component, purge_cache, create_environment, trigger_deploy. Each is idempotent and returns a job. The dangerous scopes (credentials:*, exec:raw, keys:write) are never surfaced as tools.

llms.txt and markdown docs

Section titled “llms.txt and markdown docs”

These docs publish an llms.txt index at the site root and a plain-markdown “twin” of every page (append .md to a docs URL). An agent — or a coding assistant working in your repo — can pull the authoritative reference for an endpoint, scope, or error code directly into its context instead of guessing from stale training data.

Fetch the markdown twin of a docs page
curl https://docs.managed.dev/reference/error-codes.md
curl https://docs.managed.dev/llms.txt

a sample agent loop

Section titled “a sample agent loop”

A remediation agent that “checks a site’s health, runs a fix if needed, and verifies it worked” maps cleanly onto idempotent, job-returning tools:

  1. Discover. Call get_capabilities for the site so the agent knows whether exec_command is even available (it’s absent on a static runtime).

  2. Read health. Call get_insights and get_logs to find the problem — say, a plugin throwing errors after an update.

  3. Act, idempotently. Call exec_command with wp plugin update … and an Idempotency-Key. The tool returns a job; the agent waits on it. A retry replays the same job rather than updating twice.

  4. Verify. Call get_insights again and confirm the error rate dropped. If it didn’t, the agent can escalate or roll back — every step it took is in the audit log under the key’s identity.

This is the whole point of the design: bounded scopes, idempotent writes, and job-backed verification turn an agent from a liability into a careful operator. The richer scope model and deeper application-layer surface let the server go further than a generic-PaaS agent could — it can reach the WordPress layer, not just compute.

next steps

Section titled “next steps”
API ecosystemHow one spec generates the MCP server, SDKs, CLI, and Terraform provider.
ScopesThe scope grammar that bounds every tool the agent can call.
Capability discoveryHow an agent asks a site what it can do before acting.
IdempotencyWhy a retrying agent is safe — replays return the original job.