Connect AI Agents (MCP)

Let an AI assistant or coding agent inspect your apps, read their logs, redeploy them and manage variables, with an API key you scope.

Cosmoner runs a Model Context Protocol server for your project. Connect an AI tool that supports MCP — Claude Code, Cursor, VS Code and others — and it can look at your apps, read their build and runtime logs, redeploy them and set variables, all from the conversation.

https://api.cosmoner.com/v1/mcp

The server is a thin layer over the API: every tool is one API call, made with the API key you give the client. So the agent can do exactly what that key is allowed to do — nothing more — and every action shows up wherever an API call with that key would.

Only want your assistant to read the documentation? The docs MCP server needs no key and cannot see your account.

1. Create a key for the agent

Create an API key for the project, named after the tool that will use it, with only the scopes the agent needs:

To let the agent…	Give the key
See your projects	`projects:read`
Inspect apps, logs and deployments	`apps:read`
Redeploy apps	`apps:read`, `apps:write`
Inspect servers	`servers:read`
Read variables	`variables:read`
Set variables	`variables:read`, `variables:write`
See which secrets exist	`secrets:read`

Redeploying also needs a key owned by a member with write access to the project, and setting variables a key owned by an owner or admin — the same rules as the API.

2. Add the server to your tool

The key goes in an Authorization: Bearer header. In Claude Code:

claude mcp add --transport http cosmoner https://api.cosmoner.com/v1/mcp \
  --header "Authorization: Bearer $COSMONER_API_KEY"

Other tools take the same URL and header in their MCP configuration, usually something like:

{
  "mcpServers": {
    "cosmoner": {
      "url": "https://api.cosmoner.com/v1/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Treat that file like any other credential: keep it out of version control, and revoke the key from the control panel if it leaks.

What the agent can do

Tool	What it does	Scope to grant
`list_projects`	Lists the projects the key can reach	`projects:read`
`list_apps`	Lists the project's apps with their status	`apps:read`
`get_app`	One app's configuration and status	`apps:read`
`get_app_logs`	The latest build or runtime log lines	`apps:read`
`get_deployment`	One deployment's phase and error	`apps:read`
`redeploy_app`	Rebuilds a git-source app and rolls it out	`apps:read`, `apps:write`
`list_servers`	Lists the project's servers	`servers:read`
`get_server`	One server's details	`servers:read`
`list_variables`	Lists variables and their values	`variables:read`
`set_variable`	Creates a variable or replaces its value	`variables:read`, `variables:write`
`list_secrets`	Lists secret names — never their values	`secrets:read`

Nothing it can do deletes a resource or creates a billable one. Tools that change something — redeploy_app and set_variable — are marked as such, so your tool asks before running them unless you have told it not to.

Whatever a tool returns is sent to the AI model your tool uses. That includes your apps' logs, which carry anything your app prints — a stray token or a customer's email address included — and your variables' values. Grant apps:read and variables:read only if you are comfortable with your AI provider seeing them, and keep anything sensitive in secrets, whose values no tool can read.

A key created for a project works on that project without saying so; every tool also takes an optional projectId.

When the agent is refused

The agent sees the same errors the API returns, worded for it to act on:

INSUFFICIENT_SCOPE — the key is missing a scope. The agent says which; add it to the key under API keys, or issue a new one.
FORBIDDEN — the key belongs to a different project, or its owner's role does not allow the action.
UNAUTHORIZED or INVALID_API_KEY — the header is missing or the key has been revoked.

Builds are rate-limited per project and run one per app at a time, so a redeploy_app straight after another one may be refused until the first finishes.

1. Create a key for the agent

2. Add the server to your tool

What the agent can do

When the agent is refused

On this page