MCP server
BetaLet an AI agent use Deplo with the same permissions a person has.
Beta
This feature is currently beta/experimental and subject to change. It is not recommended for production. Try it out and share your feedback on our GitHub.
Let an AI agent deploy an app, read logs, check why a build failed or restart a database. Deplo
speaks the Model Context Protocol (MCP) at https://deplo.example.com/api/mcp, and every tool goes
through the same permission checks a person goes through.
Three things decide what an agent may do:
- Allow AI agents, a team switch in Settings -> General, on by default for a new team. Changing it needs Manage team settings. Off, every agent stops working in that team.
- Connect AI agents (
manage_mcp), a capability. Without it in a team, none of your agents reach that team. - The token. An agent signs in with a normal API token and does only what its capabilities allow, never more than its owner can still do.
Connect an agent
Open Settings -> AI agents, in the Account group. It shows only with Connect AI agents.
Turn AI agents on
Only if the team has them off: Turn on AI agents for this team (needs Manage team settings).
Pick the agent
Claude, ChatGPT, Claude Code, Cursor, VS Code, Windsurf, Antigravity, Gemini CLI, Codex CLI, or Something else for any client that speaks Streamable HTTP.

Create a token
Set Permissions, Access and Expires (90 days by default), then click Create token. Permissions start from a template: MCP & AI agents, the default, reads the team and restarts or redeploys apps; Agent setup also creates projects, apps and databases and uses your Git connections, for an agent setting up Deplo. Access left empty reaches every team you can connect agents to.

Paste the config
Copy what the page shows into the agent's settings for your whole machine, so Deplo is there in
every folder you open. The token is shown once: leave before the agent connects and you need a
new one. Replacing a token in Claude Code? Run claude mcp remove Deplo -s user first.
Start the agent
Deplo waits for its first call: start the agent, or ask it to list its tools. After five minutes without one, Check again appears. Done starts over for the next agent.
Claude and ChatGPT skip the token step: add the address as a custom connector, then approve on Deplo's OAuth consent screen, which creates the token. They need the panel served over HTTPS.
On connect, the agent is told Deplo's vocabulary (App, Project, Environment, Folder, Server), how to change team, and where this manual is. You do not have to explain the product.
Link to a step
A link can preselect the agent and the template, as the agent setup
does: https://deplo.example.com/settings/agents?agent=claude-code&step=permissions&preset=agent.
agent takes claude-web, chatgpt, claude-code, cursor, vscode, windsurf,
antigravity, gemini-cli, codex-cli or other; preset takes readonly, ci, mcp,
automation or agent. A link never preselects Root access.
Working in several teams
A connection reaches every team where its owner may connect agents. Each call runs in one:
whoaminames the default team;list_teamslists every team and whether the agent can act there.- Every tool takes an optional
teamargument (id or slug). That is how the agent changes team. findsearches every team at once and says which team each result is in.- A terminal agent can set its default team with the
X-Deplo-Teamheader (wire reference).
Apps with more than one container
On a Compose app, a domain, a cron job and a log read name which container by its compose
service name. get_app returns the compose file with the names:
get_app slug: analytics -> the compose file
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- One hostname can serve a second container under a path such as
/api. update_domainmoves a hostname to another container without deleting it.- Without a service, a cron job runs in the container the app's domain routes to, and a log read uses the app's own container.
- A domain cannot point at a service that claims one of Deplo's
six reserved names (
deplo,traefik,postgresand three more).
See and revoke what is connected
- Settings -> AI agents: N agents connected lists yours, across every team. Edit changes what one may do, Remove cuts it off at once, in every team it reached.
- Settings -> API tokens lists them too, marked as agents, with Revoke.
- The team sees only counts: Settings -> General for the team, Settings -> Members per member. To cut off someone else's agents, take away their Connect AI agents or Use API tokens capability, or remove them from the team.
Creating, editing and revoking a token is recorded in Activity, with who did it.
What an agent can and cannot do
Can, if the token allows it: almost everything the dashboard does, from apps and Compose files to backups, members and Git connections. A token with the instance admin bit also manages servers, certificates, Docker cleanup, the panel's address and updates.
Cannot, ever: reveal a secret. No tool exposes one, whatever the token allows.
Deplo adds no confirmation step of its own. Destructive tools are flagged so the agent's client can ask you first. If yours does not ask, give it a token that cannot do what you would not want done, scoped to one project, folder or app if that is all it needs.
Troubleshooting
| Symptom | What to check |
|---|---|
The team "Acme" has turned off MCP access | Allow AI agents is off in that team's Settings -> General. |
You may not connect AI agents to the team "Acme" | You lack Connect AI agents there. The reply lists the teams the connection can still use. |
| Every call is refused | The token lacks the capability, or the team requires two-factor and the token's owner has not enrolled. |
That API token is not valid | The token expired or was revoked. Create a new one. |
| The same refusal keeps coming back | The agent passes an argument the tool does not take. The reply names it and lists the valid ones. |
| The agent cannot reach the endpoint | The panel address must be reachable from where the agent runs, over HTTPS for Claude and ChatGPT. |
| AI agents reads Outside your access | Your role reaches only part of the team. Connecting an agent needs all of it. |
More in Sign-in and access troubleshooting.
When no tool fits
graphql_query reads and graphql_mutate writes anything in Deplo's API, with
the same permission checks. Whatever the token allows, they never return a credential (a
password, connection string, token or install command) and never run a command inside a
container. graphql_mutate is always flagged destructive.
Every tool
The full list, with the capability each tool needs, is on MCP tools.
Next steps
Did this page help you?