Connect an agent

1. Create a token

In Beck, open Settings → Tokens and create a token. Name it after the agent that will use it, for example Claude Code or Cursor, because that name is how the agent shows up on tasks, progress notes and Now. Tokens start with beck_.

2. Add the server to your agent

Claude Code, with the plugin (recommended). The plugin installs the MCP server and two hooks: one resumes from Beck at the start of each session and after compaction, and one asks the agent to record the plan when you approve it and leave plan mode. It asks for your token when you install it.

/plugin marketplace add beckhq/beck-plugin
/plugin install beck@beck

Claude Code, server only. If you don’t want the hooks, add the server with the Claude Code CLI, restart, and run /mcp to check it’s connected.

claude mcp add beck --transport stdio \
  -e BECK_API_TOKEN=beck_your_token_here \
  -e BECK_API_URL=https://beck.bot \
  --scope user -- npx -y @becklabs/beck-mcp-server

Cursor. Install Beck from the Cursor Marketplace and set BECK_API_TOKEN under Plugins → Configure. Or paste the block below into ~/.cursor/mcp.json.

Any other MCP host (Claude Desktop, Windsurf, Codex, Grok and others). Add this block to the host’s MCP config. If its schema uses servers instead of mcpServers, keep the same command, args and env.

{
  "mcpServers": {
    "beck": {
      "command": "npx",
      "args": ["-y", "@becklabs/beck-mcp-server"],
      "env": {
        "BECK_API_TOKEN": "beck_your_token_here",
        "BECK_API_URL": "https://beck.bot"
      }
    }
  }
}

Environment variables

3. The first session

The agent reads the live skill first. Then it calls whoami to see whether the repo is bound to a workspace. If it isn’t, it uses the workspace you name and calls bind_workspace, or lists your workspaces and asks. After that, calls from the repo don’t need a workspace id. From then on it follows the task loop: resume, record_plan when you approve a plan, then start, check in and finish.

The tools

Every tool the server exposes, grouped by what it’s for.

Troubleshooting

Tools are missing. If record_plan, resume, bind_workspace or ask_decision aren’t there, or log_progress has no checks argument, the server is older than 1.5.0. Run npx -y @becklabs/beck-mcp-server@latest, or restart the host so npx fetches the latest.

The server doesn’t connect. Check that BECK_API_TOKEN is set in the host’s config, not only in your shell, and that the token still exists in Settings → Tokens. In Claude Code, /mcp shows the server’s status.

Several bots share a channel. Give each its own token named after it. A coordinator token can create those with create_api_token. See autonomy for who accepts whose work.