# Connect Claude Code to Aria

> Add Aria's MCP server to Claude Code with claude mcp add, or let aria init do it. Exact commands, scopes, a .mcp.json example and a check.

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

To connect Claude Code, run `aria init` in your repository, or add the server yourself with `claude mcp add --transport http`. The server address is `https://api.getaria.cloud/mcp/w/<app id>` and the key goes in an `Authorization: Bearer` header. Claude Code then sees Aria's tools in that project.

## What is the easiest way?

```bash
curl -fsSL https://api.getaria.cloud/v1/downloads/cli/install.sh | sh
aria login
aria init
```

`aria init` makes a key for this app only and adds it to Claude Code for this project (local scope, so the key stays out of your repository). It also installs the Aria skill and a short section in `AGENTS.md`. If the server is already connected, it says so. Run `aria init --reconnect` to replace the key. Add `--no-mcp` to skip the connection.

## How do I add the server by hand?

Make a key under **AI & MCP**, then **Make a key**, and run:

```bash
claude mcp add --transport http aria-myapp https://api.getaria.cloud/mcp/w/wsp_YOURAPP \
  --header "Authorization: Bearer YOUR_KEY"
```

Replace `aria-myapp` with any name, `wsp_YOURAPP` with your app's id, and `YOUR_KEY` with the key. The dashboard prints this command with your values filled in.

## Which scope should I use?

Add `--scope` to choose where Claude Code stores the server.

| Scope | Where it applies |
|---|---|
| `local` (default) | You, in the current project only. Stored in `~/.claude.json`. |
| `user` | You, in every project. Stored in `~/.claude.json`. |
| `project` | Everyone on the project, through a `.mcp.json` file in the repository. |

```bash
claude mcp add --transport http --scope user aria-myapp \
  https://api.getaria.cloud/mcp/w/wsp_YOURAPP \
  --header "Authorization: Bearer YOUR_KEY"
```

Do not use `project` scope with a literal key: the key would be committed to git.

## Can I share the setup without sharing the key?

Yes. In a `.mcp.json` at the repository root, read the key from an environment variable:

```json
{
  "mcpServers": {
    "aria-myapp": {
      "type": "http",
      "url": "https://api.getaria.cloud/mcp/w/wsp_YOURAPP",
      "headers": {
        "Authorization": "Bearer ${ARIA_MCP_KEY}"
      }
    }
  }
}
```

Each person makes their own key and exports it before starting Claude Code:

```bash
export ARIA_MCP_KEY=YOUR_KEY
```

## How do I check that it works?

```bash
claude mcp get aria-myapp
```

Inside Claude Code, run `/mcp` to see the server and its tools. Then ask:

```text
Use Aria to show the status of this app.
```

## What should I ask it to do?

```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.
```

Saving the file does not deploy it. Deploy with `aria deploy --wait`, or let your agent ask Aria to launch the app. Launching waits for your approval. See the [safety model](https://getaria.cloud/docs/mcp).

## What if it does not connect?

- A `401` means the key is wrong, expired or revoked. Make a new one under **AI & MCP**.
- A `404` means the app id is wrong, or the key is for a different app.
- If the server connects but a tool says it needs approval, open **AI & MCP**, then **Approvals**, and decide.
- Remove an old entry with `claude mcp remove aria-myapp` before adding it again.

Next: [Connect Cursor to Aria](https://getaria.cloud/docs/agents/cursor)