Skip to main content

MCP Server

@burdenoff/workspaces-mcp is the official Model Context Protocol server for Burdenoff Workspaces. It lets AI clients such as Claude Desktop, Claude Code, Cursor and VS Code work with your workspaces: members and projects, files, tags, conversations, notifications, scheduled jobs, integrations and more. It calls the same GraphQL gateways as the Workspaces app, with your session, so the same permissions apply.

  • Transports: stdio (default) and streamable HTTP
  • Sign-in: device code, email and password, API key, or headless tokens
  • Safety: tools that destroy data run only when the call passes confirm: true

Install​

npm install -g @burdenoff/workspaces-mcp
# or run it on demand
npx -y @burdenoff/workspaces-mcp

Node.js 24.11 or newer (or Bun 1.3.14 or newer).

Connect a client​

Claude Desktop, Cursor and most MCP clients read a mcpServers block:

{
  "mcpServers": {
    "workspaces": {
      "command": "npx",
      "args": ["-y", "@burdenoff/workspaces-mcp"]
    }
  }
}

With Claude Code:

claude mcp add workspaces -- npx -y @burdenoff/workspaces-mcp

Sign in​

Ask the assistant to sign you in, or call the tools yourself:

  1. workspaces_auth_login starts a device-code sign-in and returns a URL and a code. Open the URL, approve, then call workspaces_auth_complete. workspaces_auth_sign_in takes an email and password instead, and workspaces_auth_login_with_api_key takes an API key.
  2. workspaces_auth_workspaces lists the workspaces you belong to.
  3. workspaces_auth_select_workspace binds one. Every workspace tool then acts on that workspace.

The session is stored in ~/.config/workspaces-mcp/ with owner-only permissions. workspaces_auth_status shows the current session and workspaces_auth_logout clears it.

Headless use (CI, servers)​

Pass the session through the environment instead of signing in:

VariableMeaning
WORKSPACES_ACCESS_TOKENUser access token
WORKSPACES_WORKSPACE_TOKENWorkspace token for the bound workspace
WORKSPACES_WORKSPACE_IDWorkspace to bind
WORKSPACES_ORGANIZATION_IDOrganization of that workspace
WORKSPACES_API_KEYAPI key, instead of tokens
WORKSPACES_WORKSPACE_ENDPOINTWorkspace gateway (default https://graphqlworkspaces.burdenoff.com/workspaces/graphql)
WORKSPACES_GLOBAL_ENDPOINTGlobal gateway (default https://graphql.burdenoff.com/global/graphql)

What the server exposes​

Tools​

About 340 tools, each prefixed workspaces_:

AreaExamples
Sessionauth_login, auth_complete, auth_status, auth_select_workspace, profile, sessions, MFA, API keys
Workspacesworkspace_current, workspace_list, workspace_get, workspace_create, workspace_update
Peopleworkspace_members_list, workspace_members_add, groups_*, organizations_*
Projectsworkspace_projects_list, workspace_projects_get, workspace_projects_create
Activityworkspace_activity (audit trail)
Filesfiles_browse, files_list, files_get, files_download, files_upload_initiate and files_upload_complete, files_share, files_share_revoke
Tagstags_vocabularies_list, tags_list, tags_create, tags_assign, tags_entity_list
Conversationsconversations_list, conversations_search, conversations_messages_list, conversations_messages_send, threads, reactions, drafts
Notificationsnotifications_*
Automationscheduler_*, integrations_*, channels_*, export_*
Accountbilling_*, support_*, security_*, devportal_*, rbac_*, tours_*

File contents never travel through the MCP connection. Downloads return a short-lived presigned URL, and uploads return presigned URLs to PUT the bytes to.

Resources​

  • workspaces://workspace/guide: how a workspace is organised and which tools operate on each part.
  • workspaces://workspace/current: the workspace this session is bound to.

Prompts​

  • workspaces-workspace-orient: pick a workspace and summarise its members, projects, files and recent activity.
  • workspaces-workspace-find-file: find a file by name, type or tag, and optionally share it.
  • workspaces-workspace-digest: summarise recent activity, unread conversations and new files.

Security model​

  • The server acts as you. The gateways enforce the same role-based access as the app, so a tool can only read or change what you can.
  • Tools that delete, remove, revoke or otherwise destroy data are marked destructiveHint and refuse to run unless the call includes confirm: true. Your client should ask you before it confirms.
  • In HTTP mode the server listens on 127.0.0.1 unless you change it.

HTTP transport​

workspaces-mcp --http             # http://127.0.0.1:3000
workspaces-mcp --http --port 3101