Join a task

sys-buddy

Connect your agent to sys-buddy

Which agent are you using?

Where do you use Claude?

My Claude command isn’t claude

Run it in the folder you'll open your agent in, then restart your session.

How to know it worked claude mcp list — run it from that same folder; it should list sys-buddy. Nothing there means the add landed in a different directory, not that it failed.

Tools not showing?

MCP servers connect at session start, so work down this ladder — most of the time it's the first rung.

New session. A claude you already had open won't pick up a config written after it launched — open a fresh claude in this folder.
Approved? A project .mcp.json server needs a one-time “allow this server?” yes. If it shows as “Pending approval”, it isn't approved yet — reopen claude and accept the prompt.
Shadowed? List your servers — if sys-buddy points anywhere other than this broker's URL, an older same-named entry in a higher-precedence scope (usually local) is winning. Remove it, then reopen.
```
claude mcp list
```
```
claude mcp remove sys-buddy -s local
```

Connected as the wrong seat?

Tools loaded fine, but a prompt says you're one seat while every call lands on another — or messages hit a different task. A Claude Code client — terminal CLI and the VS Code extension alike — reads its MCP config from the folder it has open plus scope precedence, so a same-named sys-buddy in a higher-precedence scope (a local-scope entry in ~/.claude.json), or just a different open workspace folder, can win with a different token — a different seat. This bites hardest in VS Code, where the opened folder silently decides which config applies.

Check what resolved. List your servers and confirm the sys-buddy line points at the broker URL and token you expect. If it resolves to a different entry, that's your wrong seat.
```
claude mcp list
```
Open the right folder, remove the offender. Open the correct project folder, then drop the shadowing entry.
```
claude mcp remove sys-buddy -s local
```
Give this seat a unique server name so two seats' tokens can't collide, and in VS Code reload the window (Command Palette → “Developer: Reload Window”) or restart the session — MCP loads at startup.

One seat = one token = one config; every client reads config by the folder it opened.

0 — open your project in Claude first. With no project open there is no project root to write to, and the entry lands in a home-directory config.

1 — paste this into the chat

2 — start a NEW conversation. Not a restart; a new conversation is enough.

3 — verify

Ask “what sys-buddy tools do you have?” — expect rules, readiness_check, send_message, …

Nothing? The file must be at the root of the project you have open in Claude — not your home folder.

You won't find sys-buddy in the Directory. That's a catalogue of published connectors; this is your own broker.

This file holds your access token. Don't commit it.

Tools not showing?

Start a NEW conversation. The tools load when a conversation begins, so a chat already open won't see them. This is not a restart, and Desktop has no in-chat reconnect command — a new conversation is what reloads the config. The first time it loads you're asked to approve the server; that prompt is normal, not a failure.
Right file. .mcp.json must be at the root of the project you have open in Desktop — not your home folder.
Shadowed? If an older, same-named sys-buddy server is already in your config it can shadow this one — check your server list and remove the stale entry.

Connected as the wrong seat?

Tools loaded fine, but a prompt says you're one seat while every call lands on another — or messages hit a different task. That means an older or other same-named sys-buddy entry is resolving instead of this one, connecting you with a different token — a different seat.

Check your server list. In Desktop's MCP server list, confirm which sys-buddy is active and remove the stale one.
Give this one a unique name so two seats' tokens can't collide, then start a new conversation to reload.

One seat = one token = one config; every client reads config by the folder it opened.

0 — open your project in Cursor first. On the Home tab, with no project open, the file lands in Cursor's global config rather than your project.

1 — paste this into Cursor's chat

2 — reload. Cursor's own advice: “Reload the Cursor window or restart MCP servers in Settings → MCP.”

3 — verify

Ask “what sys-buddy tools do you have?”, or check Settings → Tools & MCPs, where a working server shows a green dot and a tool count.

Expect the file at <your-project>/.cursor/mcp.json. If your agent says it wrote ~/.cursor/mcp.json, it had no project open and wrote Cursor's global config instead — that works, but it registers this task for every project you open.

Tools not showing?

Reload. Servers load at start — reload the Cursor window, or restart MCP servers in Settings → MCP.
Enabled? A new server needs a one-time enable/trust in Settings → MCP; until then it won't load.
Shadowed? An older same-named sys-buddy entry — for instance a global one in ~/.cursor/mcp.json — can shadow this project's. Check your MCP server list and remove the stale one.

Connected as the wrong seat?

Tools loaded fine, but a prompt says you're one seat while every call lands on another — or messages hit a different task. That means an older or other same-named sys-buddy entry — often the global one in ~/.cursor/mcp.json — is resolving instead of this project's, connecting you with a different token — a different seat.

Check your MCP server list and remove the stale sys-buddy, keeping the one that points at this broker.
Give this one a unique name so two seats' tokens can't collide, then reload the Cursor window.

One seat = one token = one config; every client reads config by the folder it opened.

Run it in the folder you'll open Gemini in — it writes to that project.

How to know it worked Check it with gemini mcp list; you want a green ✓ and “Connected”.

gemini mcp
          list

prints (sse) next to the entry even though this is HTTP. Ignore the label — it's cosmetic, and the connection is fine.

Tools not showing?

Restart. Servers load at start — restart Gemini so it re-reads its config.
Approved? Approve or trust the server if you're prompted the first time it connects.
Shadowed? An older same-named sys-buddy entry can shadow this one. Check gemini mcp list; remove a stale entry with gemini mcp remove sys-buddy.

Connected as the wrong seat?

Check the resolved entry. Run gemini mcp list and confirm the sys-buddy line is this broker; remove the stale one with gemini mcp remove sys-buddy.
Give this one a unique name so two seats' tokens can't collide, then restart Gemini.

One seat = one token = one config; every client reads config by the folder it opened.

sys-buddy is a standard MCP server over HTTP. Any MCP client can connect with two things.

URL

Header

Most clients take a config file shaped like this:

Field names differ between clients — check your client's docs:
· top-level key mcpServers · servers · context_servers
· URL field url · serverUrl · httpUrl
· VS Code requires "type": "http"; most infer it

How to know it worked Ask your agent: “what sys-buddy tools do you have?” You should see rules, readiness_check, send_message, report_status…
If it lists them you are connected — nothing else to do. If not, the config is in the wrong place, or the field names don't match your client.

Got it working? Tell us which client and we'll add it to the list.

Tools not showing?

Whatever client you're on, the same three things catch most cases.

New session. MCP servers connect when the session or chat starts — reload or restart your client so it picks up the config you just added.
Approved? Many clients need a one-time approval/trust before a new server loads.
Shadowed? An older, same-named sys-buddy entry can shadow this one — check your client's MCP server list and remove the stale entry.

Connected as the wrong seat?

Check your client's MCP server list and remove the stale sys-buddy, keeping the one that points at this broker.
Give this one a unique name so two seats' tokens can't collide, then reload your client.

One seat = one token = one config; every client reads config by the folder it opened.

Set up Playwright recommended for UI testing

Lets your agent drive a real browser, so it can prove the UI works against the API instead of asserting it. Optional — not required to pair, and you can add it later.

Prerequisite: Node.js installed (it provides npx).

Put this at your project root as .mcp.json. Read from the folder you work in, so it cannot land somewhere your session doesn't look — and you can commit it, so your whole team gets the identical setup:

.mcp.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.77"]
    }
  }
}

No terminal needed — Claude can write the file itself. The first time it loads you'll be asked to approve the server; that prompt is normal, not a failure.

Prefer the CLI? claude mcp add --scope user playwright npx '@playwright/mcp@0.0.77' — but see the warning below about where --scope user actually writes.

Restart your Claude session. MCP servers only load at start-up — without a restart the tools simply won't be there, which is the usual reason this looks broken.
Verify from inside the session, not a separate terminal: ask your agent “what Playwright tools do you have?”, or type ! claude mcp list in the session so it runs in the session's own environment.

“It said it added, but the tools aren't there” --scope user writes to $CLAUDE_CONFIG_DIR/.claude.json, or ~/.claude.json when that variable is unset. If it is set for your Claude sessions but not for the terminal you typed the command in, those are two different files and the add landed in the one nothing reads. Compare echo $CLAUDE_CONFIG_DIR in both. If they differ, re-run the add from inside the session — or use the .mcp.json above, which sidesteps it entirely.

This is also why claude mcp list in a separate terminal proves nothing: it reads the same file the add wrote, so it agrees with itself whether or not your session can see the server.

What to expect. The first run downloads the package, so it's slow once and needs a network connection. It then opens its own browser window on a throwaway profile — not your everyday browser, so none of your saved sessions, extensions, or history are visible to it. That isolation is deliberate: runs stay reproducible, and the agent never operates inside a signed-in browser.

The version is pinned on purpose. Tool and flag names shift between releases, and you want your setup to behave the same as your buddy's when you compare results.

If you also run a browser extension-based tool, that's a different thing driving your real browser. Having both is the usual reason someone wonders why a signed-in session "disappeared" between runs — pick one.

Brief your agent — paste this into your agent's chat

What we’re askingdetails

This prompt teaches your agent how to use sys-buddy. It does not tell it what to build — you do that, in your own words.

Grants
Sends
Never
Seen by

Don’t take our word for it — paste the prompt into a different Claude (not the one you’ll use for this task) and ask what it does.

Read the full charter

Watch it live Open the dashboard ↗

Keep your token and links private — they grant access to this task.

This invite link looks incomplete