> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your AI agent

> Add Ankra to Claude Code, Cursor, Codex, the Claude app or any MCP client in about a minute, choose what it may do, and give it a first job.

At the end of this guide your coding agent reaches Ankra through its [MCP server](https://docs.ankra.ai/platform/mcp-server.md), and you have watched it do a first job. It takes about a minute and starts in your terminal or in the agent's settings. The agent acts as you: it can see and do what your role allows, or only read, as you choose.

## Before you start

* **An Ankra account with a confirmed email address.**
* **The agent on your computer**: Claude Code, Cursor, Codex, the Claude app, or any client that signs in to a remote MCP server in the browser. On a phone, the choice says **Needs your computer: email yourself the step**, and the page offers to mail you a link that opens the same step on your computer.
* **For Codex**, the [Ankra CLI](https://docs.ankra.ai/integrations/ankra-cli.md). The page installs it for you with Homebrew.

## Connect the agent

**1. Choose Connect my AI agent**

On **Where do you want to start?** (`/next/onboarding`), under **Connect my AI agent**, press **Connect my agent**.

**Check:** the heading reads **Add Ankra to your agent**, with one tab per agent: **Claude Code**, **Cursor**, **Claude app**, **Codex**, **Ankra CLI** and **Other**.

**2. Add Ankra to the agent**

Choose your agent's tab and do what it shows. The address of Ankra's MCP server is `https://platform.ankra.app/api/v1/mcp`.

> [tab] Claude Code
>
> Run this in your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http --scope user ankra https://platform.ankra.app/api/v1/mcp
> ```
>
> `--scope user` adds Ankra for every project on this computer. Leave it out to add it only for the folder you are in. Then start Claude Code (restart it if it is open), type `/mcp`, choose **ankra**, then **Authenticate**.

> [tab] Cursor
>
> Add this entry inside `"mcpServers"` in `~/.cursor/mcp.json`, leaving the other servers as they are:
>
> ```json theme={null}
> "ankra": {
>   "url": "https://platform.ankra.app/api/v1/mcp"
> }
> ```
>
> No `~/.cursor/mcp.json` yet? Create it with this entry inside `{ "mcpServers": { } }`. Then in Cursor open **Settings**, then **MCP**, and press the sign-in next to **ankra**.

> [tab] Claude app
>
> In Claude, open **Settings**, then **Connectors**, then **Add custom connector**. Paste `https://platform.ankra.app/api/v1/mcp` and leave the OAuth client ID empty. Then press **Connect** on the connector you added.

> [tab] Codex
>
> Codex reads its token from your shell, so it connects through the Ankra CLI. First choose on the page what Codex may do: **Read and change** or **Read only**. Then run the first block and finish signing in, in your browser:
>
> ```bash theme={null}
> brew install ankraio/tap/ankra
> ankra login
> ```
>
> Then run the second block in the same terminal. For **Read and change**:
>
> ```bash theme={null}
> ankra mcp connect --client codex --write
> export ANKRA_MCP_TOKEN="$(ankra mcp token --client codex)"
> ```
>
> For **Read only**, leave out `--write` and add `ankra logout` as a last line. It signs the Ankra CLI out on this machine, for you and for anything else that was using it, so Codex keeps only the access you chose:
>
> ```bash theme={null}
> ankra mcp connect --client codex
> export ANKRA_MCP_TOKEN="$(ankra mcp token --client codex)"
> ankra logout
> ```
>
> Start Codex in the same terminal. A new terminal needs the `export` line again. The token lasts 90 days. Running the connect line again replaces it and ends the old one. Every program started from that terminal can read the token, so think twice before you put the `export` line in your shell profile.

> [tab] Ankra CLI
>
> ```bash theme={null}
> curl -fsSL https://ankra.ai/install | sh
> ```
>
> It installs the Ankra CLI, checks the download against its published checksum and never uses `sudo`. A browser tab opens on Ankra: check that its code matches the one in your terminal, then approve the sign-in. Back in the terminal it asks before each thing it sets up: a free playground when you have no cluster yet, Ankra's skills for the coding agents it finds on this computer, and a read-only MCP connection for Claude Code.
>
> The CLI signs in as you, and so does any agent that runs it: there is no read-only sign-in. It stays signed in for 90 days, or until you run `ankra logout`. On Windows, run `irm https://ankra.ai/install.ps1 | iex` in PowerShell. With Homebrew, run `brew install ankraio/tap/ankra`, then `ankra onboard`.

> [tab] Other
>
> Add a remote MCP server in your agent with the address `https://platform.ankra.app/api/v1/mcp` (HTTP transport), then start its sign-in for the server.

**Check:** the page says **Waiting for** *your agent* **to connect** (for Codex, **to make its first call**), and notices on its own when it does.

**3. Approve the sign-in**

For Claude Code, Cursor, the Claude app and Other, a browser tab opens on Ankra. It names the agent, lists what it asks for, and has one **Authorize** button: you cannot narrow the access there. Press **Authorize**, and the tab hands you back to your agent. For the Ankra CLI, approve the sign-in on the tab that opened. Codex needs no approval: its access came with the connect line.

**Check:** the heading changes to **Now tell it what you want**, and the page says *your agent* **is connected. Paste this to it and watch it work here.**

**4. Give it a first job**

The page offers a first sentence. Press **Copy** and paste it into your agent. For example:

* *Create a playground on Ankra and tell me when it is ready.* It starts a [playground](https://docs.ankra.ai/get-started/playground.md): free for 24 hours, no card.
* *Show me what is running on Ankra and what needs attention.* This one only reads, and is what an agent that may only read is offered.

**Check:** the heading changes to *your agent* **is working**, and its calls to Ankra are listed as they happen, each in plain words such as **Started your playground**. When the job is done, the heading reads *your agent* **did its first job**.

## What the agent can and cannot do

The agent acts as you, inside your role. What it may do is shown under the job: *your agent* **may read and change, as you** or **may only read, as you**.

| | Read only | Read and change |
| - | - | - |
| **What it may do** | Sees what you can see, logs included, which can hold sensitive values. Never the values of Secrets. Changes nothing through this connection. | Does what you can, without asking again. |
| **What that includes** | Looking at clusters and what runs on them, logs, alerts, Stacks and applications | For a Member: deploying and deleting applications and Stacks. For an Owner or Admin: also deleting clusters, removing people, merging pull requests on GitHub and starting things that cost money. |

* **The Ankra CLI is a second way in.** The CLI stays signed in as you, and an agent that runs shell commands can use it, whatever its MCP access says. `ankra logout` ends that sign-in and leaves the agent its own token.
* **Access is never widened in place.** To let an agent that may only read change things, end its access and connect it again with more: for Codex, run `ankra mcp connect --client codex --write` again. For the other agents, end it on **API access** in your account and sign the agent in again.
* **A token with a narrower scope.** `ankra mcp connect --client claude-code` (or `cursor`, `codex`) makes a token only the MCP server accepts, read-only unless you add `--write`, pinned to the project you are acting in and expiring after 90 days. See [`ankra mcp connect`](https://docs.ankra.ai/reference/cli/mcp#ankra-mcp-connect).
* **Clusters of your own.** An agent that may change things reaches every cluster you can reach. Marking a cluster **Production** stops Ankra AI from changing it unasked, not your agent.

## Where its calls show up

* **On the agent page.** While the job runs, the page lists each call as it lands. Afterwards, **What** *your agent* **did, call by call** keeps the list.
* **In the audit log.** Every call, a refused one included, is recorded in your organisation's [audit log](https://docs.ankra.ai/guides/audit-log.md) as `mcp_tool_call`: you, the address it came from, the token and agent it came through, the tool, whether it is a tool that changes things, whether the call worked (with the error when it did not), the cluster it acted on, and the names of the arguments, not their values. What a tool answered is not recorded. The agent's answers stay in the agent.

## Manage or remove it

Under the job, **Manage or remove** opens **API access** in your account (`/next/account/api`), where every agent's access is listed and can be ended at any time. **Add another agent** connects a second one. For the **Ankra CLI** tab the button is **How to end it**: run `ankra logout`.

## Make your agent better at Ankra

Ankra publishes skills that teach an agent how the platform works: how to ship an app, read a failing deployment, write a Stack. Install them with the Ankra CLI:

```bash theme={null}
brew install ankraio/tap/ankra
ankra login
ankra skills install
```

See [Agent skills](https://docs.ankra.ai/integrations/agent-skills.md).

## What can go wrong

When the agent stays silent, the page says **No agent has connected yet** (for Codex, *your agent* **has not called Ankra yet**; for the CLI, **The Ankra CLI has not signed in yet**) and keeps watching. Open **What usually stops it**:

| Agent | What usually stops it |
| - | - |
| Claude Code, Cursor, Claude app, Other | Adding the server does not sign in: start the sign-in in the agent. If the agent was already open, restart it. If the tab opened in another browser, sign in to Ankra there. |
| Codex | Codex only has its token in the terminal where you ran the `export` line. It calls Ankra only when you ask it something that needs Ankra. If the connect line printed an error, run `ankra login`, then the connect line again. |
| Ankra CLI | No browser tab opened? The terminal prints the link: open it yourself. A sign-in link is good for 10 minutes: after that, run `ankra onboard` for a new one. If the tab opened in another browser, sign in to Ankra there. |

Still stuck? **Talk to a person** on the same page opens support.

## Where to go next

> [card] [MCP Server](https://docs.ankra.ai/platform/mcp-server.md)
>
> Every client, tokens, and how the server handles writes.

> [card] [MCP Tool Reference](https://docs.ankra.ai/platform/mcp-tools.md)
>
> Every tool the agent can call, and the scope it needs.

> [card] [Service tokens](https://docs.ankra.ai/guides/service-tokens.md)
>
> Give an agent its own identity and a narrower role.

> [card] [Try a playground](https://docs.ankra.ai/get-started/playground.md)
>
> What the playground your agent starts is, and how to keep it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.