@bldrsos/mcp

The BLDRS agent bridge. It connects Claude Code, Codex or Cursor to one BLDRS project, so your coding agent can read the plan, push tasks back, log the hours it worked, and close a milestone — against the same database your client sees.

It is a thin stdio bridge and nothing else. The tools live on the BLDRS server and are fetched when your editor connects, so an old install can never disagree with the API about what a tool does. It can only be missing a newer one, and doctor tells you when that has happened.

Requires Node 20 or newer, and a BLDRS account.

Install

There is nothing to install. Every command below is an npx call, and your editor's config runs npx -y @bldrsos/mcp mcp for you.

A global install is not recommended: the bin is pinned per project through the config init writes, and a global copy is one more thing to forget to update.

Log in

npx @bldrsos/mcp login

It asks for a token. Mint one at app.bldrsos.com → Settings → Agent tokens, picking the project it should reach. A token is bound to one project — that is the blast radius, and it is deliberate.

The token is written to ~/.bldrs/credentials with mode 600, filed under the project it reaches (the server says which; you never type a slug) and the API URL, so several clients and staging and production all coexist in one file. Logging in for a second project adds an entry; it never replaces the first. It never goes in the repo. If BLDRS_TOKEN is set in the environment, that wins and the file is not read.

Set up a repo

From the root of the repo that project lives in:

npx @bldrsos/mcp init            # Claude Code — writes .mcp.json
npx @bldrsos/mcp init --cursor   # Cursor      — writes .cursor/mcp.json
npx @bldrsos/mcp init --codex    # Codex       — appends to .codex/config.toml

All three write into the repo, never into your home directory.

With one token stored, init uses it. With several, say which project this repo is: npx @bldrsos/mcp init --project laura-rode-pllc. It refuses to guess, because pinning a repo to the wrong client's project is the one mistake it must never make on its own. (login prints the exact init line to run.)

init writes three things:

• .bldrs/project.json — the project slug, the API URL, and the schema version the repo was set up against. Commit this. It carries no secret.
• Your editor's MCP config, pointing at npx -y @bldrsos/mcp mcp. No token goes in it — the bin reads ~/.bldrs/credentials at startup and picks the entry for the slug in .bldrs/project.json.
• AGENTS.md, but only if you do not already have one. An existing AGENTS.md is never touched.

Check it

npx @bldrsos/mcp doctor

What a ✗ on each line means:

| Check | ✗ means | | --------------------- | ------------------------------------------------------------------------- | | .bldrs/project.json | this repo was never init-ed, or you are in the wrong directory | | API URL | informational; shows which server the other checks used | | Token | nothing stored for this project and no BLDRS_TOKEN — run login | | Token accepted | the server rejected it: revoked, expired, or for another API | | Token matches repo | the token reaches a different project than .bldrs/project.json names | | Tools | the server answered but offered nothing — usually a revoked token | | Schema version | the repo is pinned to an older schema than the server runs; re-run init |

doctor exits non-zero when anything real is wrong, so it works in a script.

More than one project on this machine

Nothing special. Log in once per project — each login files its token under the project it reaches — and run init in each repo. The repo's committed .bldrs/project.json names its project, and the bridge picks that project's token every time it starts. Two repos for the same client share one token; repos for different clients never touch each other's.

A repo whose project has no stored token fails with a message naming the project, rather than borrowing another project's token. And if a token from BLDRS_TOKEN (or a pre-0.2 credentials file) turns out to reach a different project than the repo names, the bridge starts, says so on stderr, and serves nothing until that is fixed.

Upgrading from 0.1: the old one-token-per-server file is still read. The next login asks the server which project that token reaches and files it there.

Log out

npx @bldrsos/mcp logout                      # the project this repo names
npx @bldrsos/mcp logout --project <slug>     # one project
npx @bldrsos/mcp logout --all                # every stored token

This removes the local copy only. Revoking is a separate act, in the portal.

Uninstall

npx @bldrsos/mcp logout --all        # the tokens (or rm ~/.bldrs/credentials)

Then remove the bldrs entry from your editor's MCP config (.mcp.json, .cursor/mcp.json, or .codex/config.toml), and revoke the token at app.bldrsos.com → Settings → Agent tokens. Deleting the local file does not revoke it; the revoke is the part that matters.

Environment

| Variable | Effect | | --------------- | -------------------------------------------------------- | | BLDRS_TOKEN | use this token; the credentials file is not read | | BLDRS_API_URL | point at another server; overrides .bldrs/project.json |

Security

• Tokens are stored server-side as a sha256 hash only. A leaked database does not yield a usable token, and BLDRS cannot show you an existing one — lose it and you mint a new one.
• The bridge exchanges your token for a 5-minute user JWT per call. It never holds a service-role key, and every write goes through the same row-level security a browser session does.
• A token reaches one project. It cannot create projects, read another client's work, or reach account-level settings.
• Tokens look like bldrs_live_…. If you use gitleaks, this pattern is worth a rule of its own so one can never be committed.
• Found a security problem? Report it privately through the contact on app.bldrsos.com rather than filing it in public.

Licence

MIT.