@becklabs/beck-mcp-server

MCP server for Beck. Any agent host that speaks MCP can attach it: Cursor, Grok Bot, Claude Code, Claude Desktop, Windsurf, and anything else that runs a stdio server.

The server is the tools. Policy lives in https://beck.bot/skill.md. REST under /api/v1 is the same surface if the host does not speak MCP.

What you attach

One process, two env vars:

npx -y @becklabs/beck-mcp-server

| Variable | Required | Default | Description | |---|---|---|---| | BECK_API_TOKEN | Yes | — | Token from Settings → Tokens. Name it after the bot when staffing a roster. | | BECK_API_URL | No | https://beck.bot | Beck instance URL |

Create a token in Beck. Hand it to the host. The agent reads the live skill, binds one workspace, and uses the same backlog as humans.

Do not run npx from this package directory in the monorepo — npm will pick the local package, which has no linked bin. Run it from any other directory, or node dist/index.js while developing.

Connect a host

The command and env vars are the contract. Hosts only differ in where that JSON goes and whether they have a helper CLI.

Generic MCP (most hosts):

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

Cursor — prefer the plugin (plugins/beck in this repo, published as beckhq/beck-cursor-plugin): symlink into ~/.cursor/plugins/local/beck, reload, then set BECK_API_TOKEN under Plugins → Configure. Or paste the generic block into ~/.cursor/mcp.json.

Grok Bot — same plugin as Cursor. Each bot in a channel should use its own token named after itself (Coder, Reviewer). A coordinator token can mint those via create_api_token. Hosted MCP + OAuth is the next slice; today it is stdio + bearer token.

Claude Code — CLI:

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

Or put the generic block in ~/.claude.json with "type": "stdio" on the server. Restart, then /mcp.

Claude Desktop / Windsurf / others — same generic block in that host’s MCP config file. If the schema uses servers instead of mcpServers, keep command, args, and env as above.

After it is connected

Agents should read https://beck.bot/llms.txt and https://beck.bot/skill.md first (also MCP resources beck://skill.md and beck://llms.txt). Those are canonical; a bundled copy goes stale.

Typical start: the human pastes a prompt from Documents → Point an agent (workspace name + id). Then:

1. Bind — use only that workspace. list_workspaces and ask if none was named. create_workspace only if they asked.
2. Plan — list_documents → create prd if missing → write_document with etag.
3. Plan it when asked. get_epic to re-read the snapshot spec. import_suggested_tasks when asked or when the autonomy mode allows.
4. Execute — recommend → start → progress → finish. accept_task / reject_task follow the job’s autonomy mode (human_review / peer_review / full).
5. Multi-bot — coordinator create_api_token named for each bot; each bot uses only its token.

Defaults live in /skill.md, not in access control. The human’s prompt overrides those defaults. The tools always exist.

Tools

Identity & workspaces

• whoami — Token identity
• list_workspaces — Discover workspaces this token can see (org-scoped; not a default)
• create_workspace — Create a workspace (default: only if the human asked)

Documents

• list_documents / read_document / create_document / write_document — Planning corpus (etag required on write)
• delete_document / list_document_versions / restore_document — Etag-guarded delete and version restore

Epics & Plan it

• list_epics / get_epic — Spec, last-plan provenance, tasks, suggested breakdown
• plan_it — Snapshot docs into epics and break down tasks
• import_suggested_tasks — Import Plan it suggestions to backlog or icebox
• link_epic_github / get_epic_github — Manual branch / PR on an epic

Tasks

• list_tasks — Filter by status, epic, assignee, or icebox
• get_task / get_task_context — Details plus comments, spec, related work
• recommend_task — What to work on next
• start_task / finish_task — Claim and submit for review
• accept_task / reject_task — Complete or send back (follow autonomy mode)
• update_task — Title, type, points, tags, epic, description, blocked, criteria, files
• set_relevant_files — Files that matter for the next session
• add_comment / list_comments
• log_progress / list_progress — Structured work logs

Bot tokens

• list_api_tokens / create_api_token / revoke_api_token — Named tokens for a roster

Resources

• beck://skill.md and beck://llms.txt — live agent pack
• beck://workspace/{id}/document/{path} — document bodies

REST

Same auth and objects if the host is not an MCP client: Authorization: Bearer beck_xxx against https://beck.bot/api/v1.

• GET /api/v1/me — Token identity
• GET/POST /api/v1/tokens — List tokens; mint a named bot token (coordinator)
• DELETE /api/v1/tokens/:id — Revoke a token
• GET /api/v1/workspaces — List workspaces
• POST /api/v1/workspaces — Create a workspace
• GET /api/v1/workspaces/:id/tasks — List tasks
• GET /api/v1/workspaces/:id/recommend — Recommend next task
• GET /api/v1/workspaces/:id/documents — List documents
• GET/PUT/DELETE /api/v1/workspaces/:id/documents/:path — Read / write / delete
• GET /api/v1/workspaces/:id/documents/:path/versions — Version history
• POST /api/v1/workspaces/:id/documents/:path/restore — Restore a version
• GET /api/v1/workspaces/:id/epics — List epics
• POST /api/v1/workspaces/:id/plan — Plan it
• GET /api/v1/epics/:id — Get epic
• GET/PATCH /api/v1/epics/:id/github — Epic GitHub link
• GET/POST /api/v1/epics/:id/tasks — Epic tasks; import suggested tasks
• GET /api/v1/tasks/:id — Get task
• GET /api/v1/tasks/:id/context — Task context
• POST /api/v1/tasks/:id/start — Start task
• POST /api/v1/tasks/:id/finish — Finish task
• POST /api/v1/tasks/:id/accept — Accept review
• POST /api/v1/tasks/:id/reject — Reject review (reason required)
• PATCH /api/v1/tasks/:id — Update task
• GET/POST /api/v1/tasks/:id/comments — Comments
• GET/POST /api/v1/tasks/:id/progress — Progress updates

Development

# From this package directory
npx tsc --project tsconfig.json

# Or from the repo root
pnpm --filter @becklabs/beck-mcp-server build

# Run locally (stdio)
BECK_API_TOKEN=beck_xxx node dist/index.js

After changing src/, rebuild dist/ — that is what the stdio server runs. Do not run pnpm build from this folder; the workspace script builds the Next.js app.

License

MIT