# Connect Beatra MCP from a headless agent
> One command. The person approves on any phone or computer; the agent finishes the setup.

Use this page when your agent runs where it cannot open a browser for the person:
an SSH server, a container, a cloud VM, or a chat bot on a VPS.

If your host can open a browser on the person's computer, you do not need this page:
add `https://mcp.beatra.ai/mcp` to the host and sign in when it asks.

## Connect in one command

Python 3.8 or newer, standard library only.

```bash
mkdir -p ~/.beatra/connector
curl -fsSL https://api.beatra.ai/oauth/connector/connect.py -o ~/.beatra/connector/beatra_connect.py
python3 ~/.beatra/connector/beatra_connect.py --host claude-code
```

1. The first run prints `BEATRA_CONNECT_PENDING`, a link and a code. Show both to the person.
   They open the link on any phone or computer, sign in to Beatra, check that the page shows
   the same code, and select **Allow**.
2. Run the same command again. Each run waits up to 90 seconds. Repeat until it prints
   `BEATRA_CONNECT_READY`. The code is valid for 15 minutes; if it expires, the next run prints a new one.
3. Reload the host's MCP servers (see the table below). Then call `beatra.tasks.list` to check
   the connection; it costs nothing.

The command never prints the token. Do not open, print, or copy its token files (`*.token`), its pending files
(`*.pending.json`), or the host configuration it wrote, and never put the token in a prompt, a command line, or a
project file.

## Pick `--host`

| Host | `--host` | What it sets up | Load it |
| --- | --- | --- | --- |
| Claude Code | `claude-code` | User-scope server `beatra` with a header helper | `/mcp` → reconnect, or restart Claude Code |
| Codex | `codex` | `[mcp_servers.beatra]` in `~/.codex/config.toml` | Start a new Codex session |
| Cursor | `cursor` | `beatra` in `~/.cursor/mcp.json` | Restart the agent, or reload the window |
| Other hosts with a JSON `mcpServers` config | `json --config <path>` (the host's user-level config, never a project file) | `beatra` with the URL and the `Authorization` header | As the host documents |
| Grok Build, and hosts that read a token file or run a header helper | `file` | A private token file and a header helper; the command prints their paths | Point the host at the printed path, then restart |

Add `--name "<your app>"` to choose the name the person sees on the approval page.

## Host sign-in

If your host supports standard MCP OAuth and can open a browser, use its normal sign-in flow.
On a server without that browser, use the command above. Follow the host’s current documentation
for remote browser forwarding. Sign in separately on each machine; do not copy token files.

## Disconnect or reconnect

- Disconnect: Console → **Devices** → **Connected apps** → **Disconnect** (or open console.beatra.ai/apps). The host's next call is refused.
- Reconnect: run the same command again. The person approves once more.
- A connection made with this command lasts until it is disconnected, or until it goes unused for a year.

## Beatra in mainland China

Use [docs.beatra.cn](https://docs.beatra.cn/zh/docs/agent-connect): the same steps with
`api.beatra.cn` and `mcp.beatra.cn`. The script downloaded from `api.beatra.cn` uses them by default.