MCP Server

The MCP server lets an AI assistant work with your Runsite account the same way you would in the dashboard: list services, read logs, check what a deployment did, and ship a new one.

You give the assistant an API key once. After that you can just ask it things in plain language:

• “Is my-api healthy?”
• “Why did the last deploy fail?”
• “Deploy my-api and tell me when it is up.”

MCP (Model Context Protocol) is the standard that assistants use to talk to outside services. Claude Code, Claude Desktop, Cursor and most other AI tools support it.

Endpoint	https://mcp.runsite.app/mcp
Transport	Streamable HTTP
Auth	An API key in the Authorization header

What is an MCP server?

MCP is a small, open standard for connecting an AI assistant to something outside itself. The assistant reads a list of tools the server offers, calls one when it needs to, and gets a structured answer back. No scraping, no guessing at URLs.

Runsite runs one of these servers for your account. The tools it offers are the things you already do in the dashboard: read logs, look at a deployment, ship a new one. Your API key decides which of them the assistant is even allowed to see.

Before you start

Create an API key on the API keys page of the dashboard. The scope you pick decides what the assistant can do:

Scope	The assistant can
read	Look at services, logs, metrics and deployments. Nothing else.
write	The above, plus deploy, start, stop and restart services, and create services, projects and databases.
admin	The above, plus set project secrets.

Start with read if you only want help with debugging. You can always create a second key later.

Caution

Whoever holds the key acts as you. Treat it like a password: keep it out of chats, screenshots and git.

Connect your assistant

Claude Code

claude mcp add --transport http runsite https://mcp.runsite.app/mcp \
  --header "Authorization: Bearer ak_live_..."

Claude Desktop, Cursor and other file-based clients

Add this to the client’s MCP config file:

{
  "mcpServers": {
    "runsite": {
      "type": "http",
      "url": "https://mcp.runsite.app/mcp",
      "headers": {
        "Authorization": "Bearer ak_live_..."
      }
    }
  }
}

Restart the client, then ask it “who am I on Runsite?”. It should answer with your email and the name of the key. That means it is connected.

Anywhere a tool asks for a service, the assistant can pass the service name or its UUID, so ordinary sentences like “restart my-api” are enough.

What the assistant can do

With a read key

Tool	What it is for
whoami	Which account and key are in use
list_projects	Your projects and how many services each has
list_services	Name, status, plan and public URL of every service
get_service	One service in detail: repository, branch, instances, plan, domains
get_service_health	Status, resource usage, last deployment and recent errors in one answer
get_logs	Recent container logs, optionally filtered by level or time
get_metrics	CPU, memory and instance count, plus the trend over a period
list_deployments	Deployment history with status, commit, branch and duration
get_deployment	One deployment, plus the tail of the build log if it failed
list_env	The names of environment variables. Values stay hidden
list_databases	Managed PostgreSQL and Valkey databases
get_database	One database and its current usage
list_plans	Plans and monthly prices for web services, PostgreSQL or Redis

get_service_health is the one to ask for when something looks wrong. It answers “what is going on with this service” in one step instead of four.

With a write key

Tool	What it does
deploy	Builds and releases the current commit. With wait it stays until the deployment finishes
start	Starts a stopped service using the image it already has
stop	Stops a service. Environment variables and disks are kept
restart	Restarts a running service without rebuilding
create_service	Creates a web service from a connected git repository
create_project	Creates a project
create_database	Creates a managed PostgreSQL database on a plan. Billed from your balance
create_redis	Creates a managed Valkey (Redis-compatible) instance on a plan. Billed from your balance
connect_database	Gives a service DATABASE_URL or REDIS_URL of a database in the same project
start_database	Starts a stopped database
stop_database	Stops a database. Its data is kept; connected services lose the connection until it starts again
set_env	Creates or updates environment variables of a service
rollback	Goes back to an earlier deployment, by default the last good one before the current

deploy and start are not the same thing. deploy builds a new version; start just brings back the version that is already built. Ask for the one you actually want.

create_service expects a repository as owner/name on a git provider you have already connected in the dashboard. Anything else is refused rather than turned into a service that could never build. Pick a plan by its slug from list_plans("web_service"); without one the cheapest plan is used.

Databases never hand a password to the assistant. create_database and create_redis generate the credentials on the server, and connect_database writes the connection URL straight into the service as a secret environment variable. The assistant only learns the variable’s name. Deploy or restart the service afterwards so it reads the new value. A database can be referred to by its name or its UUID, and a plan by its slug from list_plans or its id.

With an admin key

Tool	What it does
set_secret	Creates or updates secrets shared by every service of a project

Values you pass to set_env and set_secret are stored encrypted and never shown again: list_env returns names only. Restart or deploy the service afterwards so it reads the new values.

Deleting is done in the dashboard

The assistant cannot delete a service, a database or a project. There is no tool for it, on any scope. Ask for it and the assistant will point you to the dashboard, where you delete it yourself.

What it will not do

• Read a secret back. list_env returns names with masked values, and no tool exists that returns a value.
• Delete anything. Services, databases and projects are deleted in the dashboard only.
• Go beyond the key’s scope. With a read key the deploy tools are never listed to the assistant at all, so it has nothing to call. The scope is checked again on every call, so a client that remembers a tool name from an earlier session is refused too.
• Touch someone else’s account. Every call acts as the owner of the key.

Resources and ready-made prompts

Some clients prefer to read data instead of calling a tool:

• runsite://services is your service list as JSON
• runsite://service/{id} is one service, in the same shape

Two prompts ship with the server:

• diagnose_service walks through status, metrics, error logs and the last deployment
• deploy_and_verify deploys, waits, then checks the service came up healthy

Limits

Limit	Value
Tool calls per API key	About 60 per minute
Actions (deploy, start, stop, restart) per key	30 per minute
Creating services, projects or databases per key	5 per minute
Log output	200 lines or 8 KB, whichever comes first
Lists	50 rows, with a note saying how many there are in total
deploy with wait	300 seconds by default

If a deploy takes longer than the wait, you get the deployment id back rather than a failure. The build keeps running and the assistant can check on it later.

If something goes wrong

What you see	What it means
”The API key is invalid or revoked”	The key was deleted, rotated or expired. Create a new one on the API keys page
”This tool needs an API key with the write scope”	The key is read-only. Create a key with a wider scope
”Runsite is rate-limiting this API key”	Too many calls in a minute. Wait, and prefer get_service_health over several separate calls
The assistant says the deploy tool does not exist	It has a read key. Scope decides which tools it can even see
Nothing happens after connecting	Restart the client. Most read their MCP config only at startup

Questions people ask

Do I need to install anything? No. The server runs on Runsite at https://mcp.runsite.app/mcp. You only add the URL and your API key to your AI client’s config.

Which clients work with it? Any client that speaks MCP over Streamable HTTP works: Claude Code, Claude Desktop, Cursor and others.

Can the assistant read my secrets? No. list_env returns variable names with the values masked, and no tool returns a value. A value the assistant sets is stored encrypted and is never shown back.

Can it delete a service or a database by accident? No. There is no delete tool at all. Deleting is done by you, in the dashboard.

Can it see my database password? No. Passwords are generated on the server, and connecting a database writes the URL into the service as a secret. No tool returns it.

How is this different from the CLI? Same actions, different driver. You type commands into the CLI; the assistant calls tools over MCP. Both use the same API key and the same Public API.

See also

• API keys covers creating, rotating and revoking keys
• CLI does the same actions from your terminal
• Public API is what both of them call underneath