BTSBTS

BTS MCP — drive BTS from your AI agent

The BTS MCP server gives Claude Code, Cursor and any other MCP-aware AI agent the tools to operate everything the dashboard manages: projects, environments & deployments, env vars, services, addons, in-container command/SQL/Redis execution, CI workflows, nodes, teams, and more. It is hosted by the BTS control plane: you connect with a URL and an API key. There is nothing to install, and new tools show up as soon as BTS deploys them.

Connect Claude Code

One command, with an API key from the next section:

claude mcp add --transport http bts https://mcp.test.buildingswell.com \
  --header "Authorization: Bearer nxs_your_api_key"

Add --scope user to make BTS available in every project on your machine instead of just the current one. Run /mcp inside Claude Code to check that the bts server is connected, then ask it something like “list my BTS projects”.

The endpoint speaks MCP Streamable HTTP in stateless mode at the root of mcp.test.buildingswell.com. api.test.buildingswell.com/mcp is the same endpoint under the API host, if your network setup prefers a single hostname.

Get an API key

Create a key under Account → API Keys in the dashboard. Keys start with nxs_ and are shown once, so copy it straight into the command above. You can revoke a key from the same page at any time.

Scoped and project-pinned keys work

Every MCP tool runs through the same HTTP API routes the dashboard uses, with your key. Whatever you restrict the key to is enforced on every tool call. The scope picker narrows a key to the capabilities the agent needs: projects:read/write, deployments:read/write, env:read/write, endpoints:manage, and for CI debugging workflows:read, workflows:logs (job transcripts can echo secrets, so they are gated separately) and workflows:write (dispatch / cancel / re-run; dispatch and re-run also need deployments:exec, since a run executes steps with every secret injected). You can also pin a key to one workspace or to specific projects. A key with no scopes inherits your full access. Ask the agent to run nexos_status to see which user and restrictions the key carries. The same options are available through POST /auth/api-keys.

The key is sent with every request and BTS stores nothing on your machine. Your MCP client keeps it in its own config, so keep that config out of git. Don’t put the key in a committed .mcp.json.

Other MCP clients

Cursor and any other client that supports remote (Streamable HTTP) MCP servers use the same URL and header. In the usual JSON config format (for Cursor, ~/.cursor/mcp.json or a project’s .cursor/mcp.json):

{
  "mcpServers": {
    "bts": {
      "url": "https://mcp.test.buildingswell.com",
      "headers": {
        "Authorization": "Bearer nxs_your_api_key"
      }
    }
  }
}
Don’t use npx @nexos.rs/mcp

Older versions of these docs said to install the MCP with claude mcp add nexos -- npx -y @nexos.rs/mcp. The @nexos.rs/mcp package on npm is not BTS: it belongs to upstream Nexos and connects to api.nexos.rs, a different platform with different accounts. If you added it, remove it with claude mcp remove nexos and connect the hosted endpoint above instead. The hosted endpoint is the only BTS MCP.

Setting up a repo from scratch

The hosted server can’t see your working copy, so the work that happens inside your repo is done by the agent: working out the stack and writing a Dockerfile and nexos.yaml. The BTS Claude Code skill does this from start to finish. It writes the files and then uses the MCP tools to create the project, set env vars and wire the webhook. Any agent can follow the same steps by hand. Tools that take a file accept its contents inline: nexos_create_project_from_yaml and nexos_apply_yaml take yamlContent, and nexos_import_env_file takes the .env text.

> Set this repo up on BTS.

Claude → nexos_status
  → "Authenticated as you@github. The key inherits full access."
Claude → nexos_lookup_project_by_repo { repo: "you/my-app" }
  → no existing project

Claude → (writes Dockerfile + nexos.yaml in your repo, shows you both)

Claude → nexos_create_project_from_yaml { yamlContent: "..." }
  → "Project 'my-app' created."
Claude → nexos_set_env_vars
  → asks you for secrets; never invents them

Claude → nexos_get_webhook_info
  → prints the Payload URL, Secret, and the events to tick
You    → (paste into GitHub → Add webhook → green checkmark)

Claude → "Commit and push your branch for a preview URL in <60s."

What the MCP does

  • Creates and configures projects from a repo URL or a full nexos.yaml, including services, addons, env vars, and hooks.
  • Deploys and observes: trigger deploys, list environments, read build/deploy logs, and diagnose failures without copy-pasting error messages.
  • Fixes its own CI: the workflow tools list runs, open the red one, read the failing job’s transcript, push a fix (which runs the workflow again on the new commit), or re-run a flaky job at the same commit.
  • Operates environments: pause/resume/rebuild, reset databases, run commands, SQL and Redis directly in the environment’s containers, open external TCP endpoints.
  • Manages the account: teams, members, nodes, quotas, and the activity feed.

Tool reference

80 tools. Highlights, by area:

  • Projects & config: nexos_list_projects, nexos_create_project, nexos_create_project_from_yaml, nexos_apply_yaml, nexos_export_yaml, nexos_update_project, nexos_lookup_project_by_repo
  • Env vars & build args: nexos_set_env_vars, nexos_import_env_file (takes .env content inline), nexos_set_build_arg
  • Deployments & environments: nexos_trigger_deploy, nexos_list_environments, nexos_get_deployment_logs, nexos_rebuild_environment, nexos_pause_environment, nexos_reset_environment_db, nexos_cancel_deployment
  • Linked repositories (multi-repo, Enterprise): nexos_list_project_repos, nexos_add_project_repo, nexos_update_project_repo, nexos_remove_project_repo. Bind a container to a repo with repoId on nexos_create_service / nexos_update_service. nexos_get_webhook_info lists every linked repo.
  • CI workflows: nexos_list_workflows, nexos_list_workflow_runs, nexos_get_workflow_run, nexos_get_workflow_job_logs, nexos_dispatch_workflow, nexos_cancel_workflow_run, nexos_rerun_workflow_run
  • Console: nexos_run_command, nexos_db_query, nexos_redis_command, nexos_addon_console, nexos_connection_info
  • Addons & endpoints: nexos_addon_catalog, nexos_enable_addon, nexos_create_endpoint
  • Account: nexos_list_teams, nexos_invite_member, nexos_list_nodes, nexos_create_join_token, nexos_get_quotas, nexos_activity_feed, nexos_get_webhook_info, nexos_status

Anything that changes state (creating or deleting a project, setting env vars, enabling an addon, pausing or archiving an environment) is meant to be confirmed with you first. The server tells the agent so in its instructions.

Where to go next