Deploy from your editor: connect Cursor or Claude Code to DeployOS with MCP

You've got an app deployed on your own server. It's Wednesday night. Your phone buzzes: someone flagged the dashboard down. You want to know — in seconds — whether it's a bad deploy, a dead container, or DNS still propagating.

You open your editor and type:

"Run the Doctor on dashboard and pull the last 200 lines of its logs."

That's it. DeployOS runs the 9-step diagnostic over SSH, tells you what's wrong in plain English, and drops the logs into your chat. No SSH, no dashboard hunting, no context switching.

That's what the DeployOS MCP server unlocks: your coding assistant can talk to your deployment platform the same way it talks to your codebase.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants — Cursor, Claude Code, and others — call tools on your machine through a tiny local server. DeployOS ships one built in, so your editor gets a first-class view of your infrastructure without you pasting IPs, keys, or JSON into a prompt.

Here's what the server actually does under the hood: it reads the exact same servers, apps, and keychain credentials you've already set up in the DeployOS desktop app. There's no separate account, no second login, no credentials to re-enter. If it's configured in DeployOS, your assistant can see it.

What you get

Once connected, your assistant can do everything you can see — and only what you let it.

Always available, read-only (the safe stuff):

| Tool | What it does | |---|---| | list_apps / get_app | Every app across all servers, or full detail on one — domains, build method, port, replicas, health path, repo/branch | | list_servers | Every server DeployOS manages | | list_deployments | Recent deploys for a named app (feeds rollback) | | run_doctor | The 9-step diagnostic: DNS, ports, proxy, container, network, route, health, TLS, logs | | fetch_logs | Recent logs for an app — the app itself or its reverse proxy | | get_server_metrics | Live CPU/RAM/disk, sampled over SSH right now | | get_app_metrics | Request-level p50/p95/p99 latency and status codes from the proxy | | list_env_var_keys | Env var names only — never their values | | list_databases / list_db_backups | Every database, and backups already taken | | list_templates | The one-click template library |

Off by default, per-tool (the powerful stuff):

| Tool | What it does | |---|---| | deploy_app | The full pipeline — fetch latest commit, build, publish route, health-check (including AI Deploy Guardrails) | | rollback_app | Roll back to a previous deployment | | restart_app / scale_app | Restart containers / change replica count | | deploy_template | Deploy a one-click app (Uptime Kuma, n8n, …) as a new app | | set_env_var | Set a single env var on an app | | run_db_backup | Take an on-demand backup, now | | manage_cron | List, add, enable/disable/remove cron jobs | | run_db_query | Run SQL/commands against a database (⚠ can write or delete — flagged destructive) | | teardown_app | Delete an app's containers, volumes, images and route (⚠ no undo — flagged destructive) |

None of the write tools are on until you explicitly turn them on — and the two most dangerous ones (run_db_query, teardown_app) get their own, extra-sensitive toggles in the UI.

How to connect it (3 steps)

1. Turn on AI assistant access in DeployOS

Open DeployOS → Settings, find the AI assistant access (MCP) card, and flip the toggle to Enabled.

That's the master switch. Until it's on, the MCP server won't start at all.

2. Point your assistant at DeployOS

Still in that card, DeployOS fills in your mcp.json for you — the path to the bundled mcp_server binary, resolved to this install, no build step needed. It looks something like this:

{
  "mcpServers": {
    "deployos": {
      "command": "/Applications/DeployOS.app/Contents/MacOS/mcp_server"
    }
  }
}

Copy that into your assistant's MCP config — usually mcp.json for Claude Code, or .cursor/mcp.json for Cursor.

Running a dev build? The app will notice the binary isn't next to it and show you the one-time build command instead (npm run build:mcp). Production installs just work.

3. Restart your assistant

MCP servers are discovered at startup, so restart your editor after saving the config. Then try the example from the top:

"list my DeployOS apps"

or

"run the Doctor on my dashboard app"

If the assistant says the tool isn't enabled, that's the permissions model talking — head back to Settings and flip that specific tool on.

How permissions actually work

This is the part worth understanding, because it's the difference between "hand your keys to the AI" and "a read-only helper you occasionally hand the keys to."

• Read-only tools are always on. Listing apps, running the Doctor, fetching logs, reading metrics — none of these change anything, so they're available the moment MCP access is on. Note that env var values are deliberately never readable; the assistant can see that DATABASE_URL is set, never what it is.
• Every write tool has its own toggle, off by default. The master switch doesn't silently imply write access. You enable deploy_app separately from manage_cron separately from run_db_query.
• A disabled tool fails loudly, not silently. Ask for something that's off and you get a clear "not enabled" message — the assistant can't just quietly do nothing and claim success.
• It reads the same keychain. Your SSH keys and credentials live in your OS keychain, managed by the DeployOS app you already trust. The MCP server uses those — nothing new to configure, nothing copied anywhere.

What you can do with it

Real workflows that take one sentence now:

• Debugging: "Pull the proxy logs for dashboard and run the Doctor — is the 502 my app or my DNS?"
• Rollback: "The last deploy to storefront broke checkout. List deployments and roll back to the previous one."
• Scaling: "It's Black Friday traffic season — scale storefront to 3 replicas."
• Config: "Set LOG_LEVEL=debug on dashboard" (then, since env vars apply on next deploy or restart, follow up with "…and restart it").
• Housekeeping: "What's the CPU on production-01?" / "Back up the analytics database now."

Is this safe?

The design goal is simple: your assistant should be able to inspect everything and change only what you explicitly allow.

• No DeployOS cloud in the loop — the MCP server is a local binary talking to your local app's data. Your secrets never leave your machine.
• Credentials come from your keychain, not from prompts or config files.
• Destructive tools are flagged as destructive in the MCP spec, so clients render the risk before the call.
• Turning a tool on is a deliberate, per-tool decision you can reverse at any time.

The mental model: the read-only half is a pair of eyes on your infrastructure, always available. The write half is a set of hands — and you decide, one switch at a time, which jobs those hands are allowed to do.

The bottom line

Your deploy platform lives on your server. Your editor is where you live. The DeployOS MCP server closes that gap — so "run the Doctor," "pull the logs," and even "deploy it" become things you type, not things you click around for.

Set it up in DeployOS → Settings → AI assistant access (MCP), paste the generated config into Cursor or Claude Code, restart, and ask. It's a one-time, three-step setup for a permanently better deployment loop.

Questions or want a deeper dive on the permission model? Email hello@mydeployos.com — a human answers.