Connecting Claude (MCP)

Cobblr ships an MCP server, so you can connect your own Claude (Claude Code, Claude Desktop, or a claude.ai connector) to your workspace and work on it by talking.

Setting it up

Two transports, one credential. Either way, mint a long-lived API token first (Your account then API tokens, and it starts cbt_), which is what Claude authenticates with, under your own permissions.

Claude Code or Claude Desktop (stdio). The server ships in the repo as packages/mcp-server. Build it once from the repo root (npm run build -w @cobblr/mcp-server), then add it to claude_desktop_config.json or a project's .mcp.json:

{
  "mcpServers": {
    "cobblr": {
      "command": "node",
      "args": ["/path/to/cobblr/packages/mcp-server/dist/index.js"],
      "env": {
        "COBBLR_BASE_URL": "https://your-instance/api/v1",
        "COBBLR_API_TOKEN": "cbt_…",
        "COBBLR_ORG_SLUG": "my-workspace"
      }
    }
  }
}

COBBLR_ORG_SLUG is optional. Set it and the per-tool workspace argument becomes optional too. The token lives only in your MCP client's config, and the server process persists nothing.

Any HTTP MCP client (including a claude.ai connector). Your instance also serves the same tool set over HTTP at POST /api/v1/hooks/mcp, authenticated by the same Bearer token, so a client that speaks remote MCP needs no local process at all.

Why it is shaped this way: your Claude runs on your side (your machine or your claude.ai account) and connects to your instance. Cobblr hosts no model and never holds your Anthropic credentials.

What Claude can do

Once connected, Claude works through the same API the app uses, and the same tool set the in-app assistant uses, so what your Claude can do and what Cobb can do stay in step:

• Read your workspace: list the kinds of record you hold and their fields, list and read records, search across every kind at once, and follow the links between records.
• Write your workspace: create a record, update fields on one, delete one, and run an action such as adjusting stock or marking a task done. Workspace settings like label-code prefixes go through the action tool too.
• Build: validate and install a bundle, or draft a new one from a description for you to review and apply.

A kind is creatable, updatable, or deletable only where its module declares that route, so Claude gets a clear "can't do that here" rather than a surprise failure. Every call is permission-checked on the server against your token's own role.

Writing needs Changes set to Auto

A connection like this has no way to show you a confirmation dialog inside Cobblr, so the workspace is stricter about what it will let through than the chat panel is.

Every write needs the chat's Changes chip set to Auto. On Ask or Off, the connection is told plainly that changes are not allowed here and what to switch to, rather than failing with something cryptic. Every change it then makes is tracked and undoable exactly like one made in the panel.

An action runs only if it can be undone. Actions declare that for themselves and the default is no, so a newly written action is cautious until someone decides otherwise. Reordering locations goes through, but printing a label, commanding a device or emptying a list does not. A refusal names the action, says why, and tells you to run it from Cobblr where the confirm step appears. The tool that lists actions marks which are which, so Claude can tell before trying.

This is the one place where what Claude can do and what Cobb can do come apart, and it is deliberate: the panel can ask you, and this cannot.

Driving and watching your screen

Claude can also share your screen session, with your permission. Once a tab is granted, it can:

• Open pages in your window. "Let me show you the low-stock view" and the view appears in your tab.
• Point at things. A visible cursor (with an optional label) shows exactly where Claude means, so "click here" comes with a here.
• Follow along, if you allow it. Claude sees the clicks and page changes you make in that tab, so it can help with what you're actually doing instead of guessing.

Driving is permissioned separately from the connection itself, in three independent layers:

1. Its own token scope. Browser driving is a distinct capability a token can carry, and a token scoped to just driving can never read or write workspace data. You choose whether Claude's token can drive, touch data, or both.
2. A standing per-workspace switch, off by default, with two on-levels: navigate only, or navigate plus observe. It's re-checked on every call, so flipping it off cuts Claude off immediately.
3. A per-session tab pick. Claude asks, your open tabs show a prompt, and you tap "use this window" in the one it may drive.

It's a shared session, not a takeover: you keep using the tab normally the whole time.

Your Claude, not ours

The MCP server is a thin, authenticated face over the REST API, and Cobblr adds no AI middleman. Claude runs on your machine and your subscription, which is what makes this fine under Anthropic's consumer terms, and it works the same against a self-hosted install.