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/mcpThe 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 |
| Read email templates | email-templates:read |
| Draft email templates and roll them back | email-templates:read, email-templates:write |
| Send email from templates | email-templates:read, email:write |
| See web hosting sites, their domains and folders | hosting:read, domains:read |
| Attach domains to sites and change what they do | hosting: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
| 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 |
list_email_templates | Lists the project's email templates | email-templates:read |
get_email_template | One template's draft, variables and published version | email-templates:read |
list_email_template_versions | A template's published versions | email-templates:read |
send_email_template | Sends email from a template | email-templates:read, email:write |
rollback_email_template | Makes an earlier version the one sends use | email-templates:read, email-templates:write |
create_email_template_draft | Creates a template as an unpublished draft | email-templates:read, email-templates:write |
update_email_template_draft | Rewrites a template's draft | email-templates:read, email-templates:write |
list_hosting_sites | Lists the project's web hosting sites | hosting:read |
list_domains | Lists the project's domains and whether each is verified | domains:read |
list_hosting_domains | The domains attached to a site and what each does | hosting:read |
list_hosting_folders | The folders inside a folder of a site | hosting:read |
attach_hosting_domain | Attaches one of the project's verified domains, or a subdomain of one, to a site | hosting:read, hosting:write |
update_hosting_domain | Switches a domain between a folder, a redirect and parked | hosting: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_templatesends a published version to real recipients. Leaveemail:writeoff 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.UNAUTHORIZEDorINVALID_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.
API Keys
API keys let you access the Cosmoner API programmatically without a browser session. Use them for CI/CD pipelines, scripts, and integrations.
Project Secrets
Store and reuse sensitive values like API keys, passwords, and tokens across your project's resources. Secrets are encrypted at rest using envelope encryption.