beatraDocs

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.

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--hostWhat it sets upLoad it
Claude Codeclaude-codeUser-scope server beatra with a header helper/mcp → reconnect, or restart Claude Code
Codexcodex[mcp_servers.beatra] in ~/.codex/config.tomlStart a new Codex session
Cursorcursorbeatra in ~/.cursor/mcp.jsonRestart the agent, or reload the window
Other hosts with a JSON mcpServers configjson --config <path> (the host's user-level config, never a project file)beatra with the URL and the Authorization headerAs the host documents
Grok Build, and hosts that read a token file or run a header helperfileA private token file and a header helper; the command prints their pathsPoint 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: the same steps with api.beatra.cn and mcp.beatra.cn. The script downloaded from api.beatra.cn uses them by default.

Last updated

Previous

Authentication & request conventions

Next

Sign-in troubleshooting

On this page

Markdown