MCP server

What it is

A way to let an AI agent drive your infrastructure: deploy an app, read logs, check why a build failed, restart a database. It speaks the Model Context Protocol (MCP), the same protocol Claude, ChatGPT and coding agents use to reach tools.

Settings -> MCP Server, visible to anyone who may connect their own agents to the team (Connect AI agents, manage_mcp) and to whoever manages the team's settings. What you connect there is yours: the token it creates is personal, listed only under your Settings -> API tokens.

Connect an agent

How it works

The endpoint is /api/mcp on your own instance. It exposes one tool per action, and each tool is a GraphQL document that runs in-process against the same schema a browser session uses.

That is the whole security design: an agent goes through the same authorization code a person goes through. There is no parallel permission system to keep in sync, and no place for a check to be forgotten.

Three things guard it:

• A team switch, on by default, deciding whether agents may drive this team at all. A token is required either way, so this is the kill switch, not what makes the endpoint safe. Changing it needs Manage team settings.
• A per-member capability, Connect AI agents (manage_mcp): a token drives a team over MCP only where its owner holds it. Take it away and every agent of theirs is refused in that team, immediately.
• A token, because MCP has no credential of its own. An agent authenticates with an ordinary API token, and what it may do is that token's capabilities, nothing more.

The server also introduces itself. On connection it hands the agent a short briefing: what Deplo is, the words it uses (App, Project, Environment, Folder, Server), how to work in another team, that a refusal is the token's capabilities talking, and a link to this manual. You do not have to teach your agent the product before it can use it.

Working in several teams

A connection reaches every team its owner may connect agents to. Every call still runs in one team:

• whoami names the team a call runs in by default.
• list_teams names every team the connection can act in, and says why one cannot be used (MCP off, or the permission missing).
• Every tool takes an optional team argument (id or slug). Passing it is how the agent changes team - there is no "switch team" step, the argument is the switch.
• find searches every team at once and says which team each hit is in.

A terminal agent can also pin its default team with the X-Deplo-Team header when it is connected.

Apps with more than one container

A Compose app runs several containers, so anything that acts on "the app" has to say which one. The names are the service names in the app's own compose file, and get_app hands them to the agent:

• A domain names the container that serves it, and its port. Two hostnames can reach two different containers of the same app, and one hostname can serve a second container under a path such as /api.
• A cron job names the container the command runs in. Without it, the job lands in whichever container of the stack happens to be up.
• A log read names the container the same way.

A typical exchange:

get_app         slug: analytics                                     -> the compose file, with the names
add_domain      appId, name: app.acme.com, service: client,  port: 3002
add_domain      appId, name: api.acme.com, service: backend, port: 3001
render_compose  appId                                               -> the routing that was written

Got one wrong? update_domain moves a hostname to another container without deleting it.

See and revoke what is connected

Your agents are your tokens: Settings -> API tokens lists them, marked with the agent's name, with Edit to change what one may do and Revoke to end it. Revoking is immediate and works in every team the agent reached: the token is the access.

A team sees a number, not the credentials: agents connected on the MCP page, and per member under Settings -> Members. To take an agent away from somebody else, take away their Connect AI agents capability, or remove them from the team.

What an agent can and cannot do

Can, if the token holds it: almost everything the dashboard does. Apps and every one of their settings, a Compose app's file itself, deployments, environment variables and shared variables, domains, databases and their configuration, logs and metrics, backups, destinations and restores, cron jobs, previews, projects, environments and folders with their grants, roles and members, notifications, git connections, and for an instance admin the fleet itself: servers, certificates, Docker cleanup, the panel's address and updates.

Cannot, ever: reveal a secret. No tool exposes one, whatever the token holds.

Deplo adds no confirmation step of its own. Destructive tools are flagged so the agent's own client can ask its user. If your agent does not ask, mint it a token that cannot do the thing you would not want it doing.

If it does not work

• The agent connects and sees no tools - MCP is off for that team.
• Every call is refused - the token lacks the capability, or the team requires two-factor and its owner has not enrolled.
• "You may not connect AI agents to this team" - you lost the Connect AI agents capability there. The reply lists the teams the connection can still act in.
• The agent cannot reach the endpoint - your panel address must be reachable from wherever the agent runs. A local IDE agent needs a route to it.
• The same refusal keeps coming back - the agent is passing an argument the tool does not take. The reply names that argument and lists the ones the tool does take.

When no tool fits

Most of what you ask for has a tool of its own. For the rest there are two:

• graphql_query reads anything in Deplo's API.
• graphql_mutate writes anything in it.

They run a query the agent writes against the same schema and the same permission checks as every other tool, so the MCP server reaches the whole API, not just the part someone thought to wrap. An agent can discover what is there by asking the schema itself.

Two things they will not do, whatever the token holds: return a credential (any password, connection string, token or install command) and run a command inside a container. Those are refused by name.

Because one write tool covers everything from a rename to a deletion, it is always flagged destructive, so your agent asks before using it.

Every tool

Deplo exposes 182 tools today, plus the two above. The number moves with the product, so treat it as a snapshot: while creating a token, See which lists them all, marks the ones that token would reach and flags the destructive ones. An agent only ever sees the tools its own token can use.

Needs is the capability the token must hold; Kind is what the agent's client is told before it runs the tool, so a destructive one is where a well-behaved client asks you first.

See also