MCP server

Beta

Let 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.

Settings -> AI agents, step 1: pick the agent you are connecting

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.

Step 2: the token Deplo creates for the agent, its permissions, scope and expiry

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.

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:

  • whoami names the default team; list_teams lists every team and whether the agent can act there.
  • Every tool takes an optional team argument (id or slug). That is how the agent changes team.
  • find searches every team at once and says which team each result is in.
  • A terminal agent can set its default team with the X-Deplo-Team header (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_domain moves 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, postgres and 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

SymptomWhat to check
The team "Acme" has turned off MCP accessAllow 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 refusedThe token lacks the capability, or the team requires two-factor and the token's owner has not enrolled.
That API token is not validThe token expired or was revoked. Create a new one.
The same refusal keeps coming backThe agent passes an argument the tool does not take. The reply names it and lists the valid ones.
The agent cannot reach the endpointThe panel address must be reachable from where the agent runs, over HTTPS for Claude and ChatGPT.
AI agents reads Outside your accessYour 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?

On this page