Cosmoner Docs
Guides

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 projectsprojects:read
Inspect apps, logs and deploymentsapps:read
Redeploy appsapps:read, apps:write
Inspect serversservers:read
Read variablesvariables:read
Set variablesvariables:read, variables:write
See which secrets existsecrets:read
Read email templatesemail-templates:read
Draft email templates and roll them backemail-templates:read, email-templates:write
Send email from templatesemail-templates:read, email:write
See web hosting sites, their domains and foldershosting:read, domains:read
Attach domains to sites and change what they dohosting:read, hosting:write, domains:read

Redeploying, sending email and writing templates also need a key acting with the developer, admin or owner role, and setting variables one acting as an owner or admin — the same role 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

ToolWhat it doesScope to grant
list_projectsLists the projects the key can reachprojects:read
list_appsLists the project's apps with their statusapps:read
get_appOne app's configuration and statusapps:read
get_app_logsThe latest build or runtime log linesapps:read
get_deploymentOne deployment's phase and errorapps:read
redeploy_appRebuilds a git-source app and rolls it outapps:read, apps:write
list_serversLists the project's serversservers:read
get_serverOne server's detailsservers:read
list_variablesLists variables and their valuesvariables:read
set_variableCreates a variable or replaces its valuevariables:read, variables:write
list_secretsLists secret names — never their valuessecrets:read
list_email_templatesLists the project's email templatesemail-templates:read
get_email_templateOne template's draft, variables and published versionemail-templates:read
list_email_template_versionsA template's published versionsemail-templates:read
send_email_templateSends email from a templateemail-templates:read, email:write
rollback_email_templateMakes an earlier version the one sends useemail-templates:read, email-templates:write
create_email_template_draftCreates a template as an unpublished draftemail-templates:read, email-templates:write
update_email_template_draftRewrites a template's draftemail-templates:read, email-templates:write
list_hosting_sitesLists the project's web hosting siteshosting:read
list_domainsLists the project's domains and whether each is verifieddomains:read
list_hosting_domainsThe domains attached to a site and what each doeshosting:read
list_hosting_foldersThe folders inside a folder of a sitehosting:read
attach_hosting_domainAttaches one of the project's verified domains, or a subdomain of one, to a sitehosting:read, hosting:write
update_hosting_domainSwitches a domain between a folder, a redirect and parkedhosting:read, hosting:write

Nothing it can do deletes a resource or creates a billable one, though send_email_template sends real email, billed like any other. Tools that change something — redeploy_app, set_variable, send_email_template, rollback_email_template, the two draft tools, attach_hosting_domain and update_hosting_domain — are marked as such, so your tool asks before running them unless you have told it not to. Detaching a domain from a site is left to the control panel and the CLI.

Designing emails with an agent

Email templates are not available yet. Until they are, the server does not offer any of its *email_template* tools.

An agent can write an email template for you: describe the email, and it creates a code template from React Email files with create_email_template_draft, or rewrites an existing one with update_email_template_draft.

The agent can't publish. A draft reaches nobody until someone on your team opens it in the editor, checks the preview and publishes it, so every email an agent writes is seen by a person before it can be sent. The agent replies with a link to the template in the editor.

A few things to know:

  • Code templates only. An agent writes React Email code. To have one change a visual template, choose Convert to code in the editor first.
  • It won't overwrite your edits. A draft update names the revision the agent read. If someone saved the draft since, the update is refused, and the agent reads the template again and redoes its change on top.
  • Sending is separate. send_email_template sends a published version to real recipients. Leave email:write off the key if the agent should only draft.

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.

On this page