MCP Server

Drive the uRun control plane from an AI agent over the Model Context Protocol — the agent-native sibling of the CLI

The uRun MCP server lets an AI agent (Claude, or any Model Context Protocol client) drive the same control plane the CLI drives — read your apps, sessions and logs, and perform audited org writes. It is authed by an org-scoped API key, exactly like the CLI.

MCP and CLI are equal siblings — no precedence

The MCP server and the urun CLI expose the same control plane with the same auth. Reach for whichever fits the harness:

MCP — agent-native tool calls. Your agent sees list_apps, query_logs, get_deploy_status, … as first-class tools and calls them directly.
CLI — scripts, CI, and humans at a terminal.

The CLI is a strict superset of the MCP surface: anything MCP can do, the CLI can do, plus deploy/serve and the local developer loop. Neither is the "real" interface — they are two faces of one API.

Connecting

Point your MCP client at the uRun server and give it an org API key (see API Keys). The key scopes every call to your org; reads and audited writes work with any key, while the agent-launch tools also require the launch-agents permission on the key.

Tool surface

The server groups its tools into three tiers by what they can do.

Read tools — any org key

Inspect what is running. None of these change state.

Tool	What it returns
`list_apps` / `get_app`	Deployed apps and one app's detail
`list_sessions` / `get_session`	Live and historical sessions
`query_logs`	Structured log search, org-scoped
`tail_build_logs`	Stream one build's logs
`get_gpu_metrics`	Per-app GPU utilization / memory
`get_runtime_health`	Per-app runtime health
`get_deploy_status`	Per-app build / deployment status
`get_usage`	Org usage and credit burn
`list_capacity_leases`	Provisioned GPU/instance capacity
`list_failure_groups`	Grouped runtime failures to triage
`get_platform_feedback` / `list_my_platform_feedback`	Your filed platform feedback

Audited write tools — any org key

Any org key may call these. Every write is attributed to the key and the user who created the key; binding a service account is optional and only gives the write a distinct named actor. None of these require the launch-agents permission.

Dashboards and view-defaults — configure the console.
Issue triage — triage_issue over failure groups.
Alert rules / channels — create and remove alerting.
Environments — manage org environments.
configure_org — org-level settings.
raise_platform_feedback / comment_platform_feedback — file and track feedback to the uRun team.
set_app_git_config / clear_app_git_config — wire an app to its connected GitHub repo.
Secrets, trusted JWKS, and org limits.

Agent-launch tools — launch-agents permission required

These spin up a server-side agent in an isolated sandbox. They also require the launch-agents permission on the key.

Tool	What it does
`run_dev_gate`	Run the dev gate for an app

Deliberately absent: spend-capable tools

Tools that spend — creating live GPU sessions — are intentionally not exposed over MCP. Sessions are created from your app's client SDK or the console, never by an agent holding an org key.

Permissions

Reads and audited writes work with any org API key.
Agent-launch tools (run_dev_gate) also require the launch-agents permission (api_keys.can_launch_agents) on the key. Keys created by an org admin or owner always have it; for other members' keys it is granted per key in the console (Settings → API Keys).

Skills: bring a CLI-first agent to parity

The MCP server gives an agent the uRun control plane natively. A CLI-first harness (one that shells out to urun instead of speaking MCP) reaches the same lift by installing the uRun skills package — @urun-sh/skills, shipped from urun-ts. Skills teach the agent the uRun workflows; MCP needs no skills because the tools are already first-class.

Install them Supabase-style with the Vercel Labs skills CLI:

npx skills add urun-sh/urun-ts

Or add the uRun Claude Code plugin marketplace:

claude plugin marketplace add urun-sh/urun-ts

The skills are CLI-centric: they give a CLI-first agent the same ops lift the MCP server provides natively. Pick one integration per harness — MCP tools or CLI-plus-skills.

Feedback

raise_platform_feedback files feedback straight to the uRun team and threads follow-ups with comment_platform_feedback; list_my_platform_feedback / get_platform_feedback track it. The CLI mirror is urun feedback.

Related:

CLI — the superset surface, including urun deploy and the local dev loop
API Keys — org keys and the launch-agents permission
Git Connect — the GitHub App behind set_app_git_config

MCP Server

On this page