# Connect a coding agent to Aria

> Give Claude Code, Cursor, Codex or another MCP client a key for one app. One command, and Aria asks you before anything risky happens.

Source: https://getaria.cloud/docs/agents (updated 1 November 2026)

A coding agent working outside Aria reaches it over MCP. Give the agent an Aria key and the address of Aria's MCP server. The key reaches one app, and you choose what it may do. `aria init` or `aria mcp add` sets this up, and the dashboard prints the exact command for each agent under **AI & MCP**. The agent can then write `aria.yaml`, deploy, read logs and check your app, while changes that matter still wait for you.

This is the second way to work with Aria. The first is [Aria AI](https://getaria.cloud/docs/aria-ai), the AI built into the Mac app and the web dashboard. It needs no key from you and no MCP set-up.

## What is MCP?

MCP, the Model Context Protocol, is how coding agents call tools on other services. Aria runs an MCP server, so your agent can look at your app and ask Aria to do things, with the same rules a person gets.

## What are Aria's MCP addresses?

| Address | Reaches |
|---|---|
| `https://api.getaria.cloud/mcp/w/<app id>` | One app. The id starts with `wsp_`. Use this one. |
| `https://api.getaria.cloud/mcp` | Every project in your workspace. |

Both use the Streamable HTTP transport and take your key as a Bearer token: `Authorization: Bearer <key>`. Keys are made in Aria, never anywhere else. A key from another service is refused.

## What is the fastest way to connect?

From your repository, with the [aria command line](https://getaria.cloud/docs/cli) installed:

```bash
aria login
aria init
```

`aria init` makes a key that reaches only this app and may operate it (routine changes run straight away, and variables, launches, DNS and deletes still wait for you), adds it to Claude Code, writes the Aria skill into `.claude/skills/aria/SKILL.md`, and adds a short Aria section to `AGENTS.md`. To connect a different agent, or an app other than the linked one:

```bash
aria mcp add --agent codex
aria mcp add --agent cursor --app wsp_YOURAPP
```

The agent names are `claude-code`, `codex`, `gemini-cli`, `antigravity`, `cursor` and `other`. You approve the key in Aria with a code, and choose what it may do. Without `--app` the key reaches every project in your workspace. Add `--can deploy,config` to ask for specific capabilities.

## How do I make a key in the dashboard?

1. Open **AI & MCP** and go to the **MCP** tab.
2. Choose **Make a key**.
3. Pick the agent, what the key reaches (one project, or the whole workspace), what it may do, and how many days it lasts.
4. Choose **Make the key**, then copy the command or the settings shown. The key is shown once.

The same tab lists every key, when it was last used and when it expires. You can change what a key may do, rotate it, or revoke it. A revoked key is refused on its next call.

## What can a key be allowed to do?

You choose these when you make a key, in the dashboard or with `aria mcp add --can`, and you can change them later.

| Capability | What it allows |
|---|---|
| `read` | Status, logs, activity and `aria.yaml`. Always on. |
| `deploy` | Build, deploy, launch, restart and roll back. |
| `config` | `aria.yaml`, variables that are not secret, domains and services. |
| `secrets.write` | Set secret values. It can never read them back. |
| `secrets.reveal` | Read a secret's value. |
| `spend` | Buy servers and domains, and upgrade plans. |
| `destructive` | Delete, destroy and restore over data. |
| `memory.write` | Note what it learns about your app. |
| `handoff` | Write `aria.yaml` with you on the setup page. |

Keep a key as narrow as the job needs. Whatever a key is allowed to do, deleting and other destructive changes always wait for you. The rules are on the [safety model](https://getaria.cloud/docs/mcp) page.

## Which agents have a setup page?

- [Claude Code](https://getaria.cloud/docs/agents/claude-code), and its [workflow guide](https://getaria.cloud/claude-code)
- [Cursor](https://getaria.cloud/docs/agents/cursor), and its [workflow guide](https://getaria.cloud/cursor)
- [Codex](https://getaria.cloud/docs/agents/codex), and its [workflow guide](https://getaria.cloud/codex)

For the whole picture on one page, read [Let your coding agent deploy](https://getaria.cloud/agents).

Gemini CLI and Antigravity can be connected with `aria mcp add`. Any other MCP client that supports a remote HTTP server and a custom header works with the address and key above.

## What should I tell my agent first?

Paste this into the agent:

```text
Use the Aria skill. Call get_stack_prompt, read this repository, write aria.yaml, check it with validate_stack_file, then save it with submit_stack_file. Ask me to enter any secret values; never print them.
```

## How do I keep the key safe?

- Put it in an environment variable or your agent's user-level settings, not in a file you commit.
- Never paste it into a chat.
- Revoke it in **AI & MCP** if it leaks. Aria never gives secret values of your app to an agent, but the key itself can act on your app.

Next: [Connect Claude Code to Aria](https://getaria.cloud/docs/agents/claude-code)