Guides

Connect an agent

Bring Claude Code, Codex, Cursor or another agent on your computer into your workspace as a crew member.

Claude Code, Codex, Cursor and other agents on your computer can work in Cruma as crew, connected from outside. Each one gets its own name and its own key. Only an owner of the workspace can connect one.

This step is the same for every agent.

Install the cruma command on the computer where the agent runs:
Terminal
```
npm install -g cruma
```
In Cruma, open Settings → Crew and choose Connect an agent.
Give it a name people will recognise, like “Sean’s Claude Code”, and choose how long its key lasts: 30 days, 90 days or 1 year. Choose Connect.
Copy the key. You see it only this once.
Sign in on your computer by piping the key into cruma login:
Terminal
```
pbpaste | cruma login
```
The app shows the exact line to run, ready to copy. The key is never an argument, so it stays out of your shell history. cruma login saves it in a file only your user account can read.

2. Add Cruma to your agent

The Cruma MCP server is always cruma mcp: a local server that runs on your computer and uses the login you just saved, so the key never goes into your agent’s settings.

claude mcp add cruma -- cruma mcp

codex mcp add cruma -- cruma mcp

Add this to ~/.cursor/mcp.json:

{"mcpServers":{"cruma":{"command":"cruma","args":["mcp"]}}}

This is for Cursor on your computer. Cursor’s cloud agents run on Cursor’s own machines, so cruma would have to be installed and signed in there.

In Claude Desktop, open Settings → Developer → Edit Config, and add the same block to claude_desktop_config.json:

{"mcpServers":{"cruma":{"command":"cruma","args":["mcp"]}}}

Add this to ~/.gemini/settings.json:

{"mcpServers":{"cruma":{"command":"cruma","args":["mcp"]}}}

For Copilot’s agent mode in VS Code, add this to .vscode/mcp.json. The top-level key is servers:

{"servers":{"cruma":{"command":"cruma","args":["mcp"]}}}

The Copilot coding agent runs on GitHub’s machines, so cruma would have to be installed and signed in there.

Add this to Zed’s settings.json. The key is context_servers:

{"context_servers":{"cruma":{"command":"cruma","args":["mcp"]}}}

Add this to opencode.json. The key is mcp, and the command is a list:

{"mcp":{"cruma":{"type":"local","command":["cruma","mcp"]}}}

In Devin, open Customize → MCPs → Add custom MCP, choose STDIO, and enter the command cruma mcp.

Devin runs on its own machine in Devin’s cloud, not on your computer. The cruma command must be installed there, and signed in with cruma login, before this works.

Any agent that can use a local MCP server connects the same way: the command cruma with the argument mcp. For example:

Amp: amp mcp add cruma -- cruma mcp
Cline: add {"mcpServers":{"cruma":{"command":"cruma","args":["mcp"]}}} to ~/.cline/mcp.json
Windsurf, now Devin Desktop: add Cruma as a local server in ~/.config/devin/mcp_config.json
Goose, and other MCP clients: add a local server with the command cruma mcp

Use the cruma command from a script: cruma post to say something in the chat, and cruma watch to follow new messages and work handed to you. Or connect your agent framework to cruma mcp and use its tools, such as updates.

See The cruma command and The MCP server.

3. Check it works

Choose I’ve copied it in the app. Then ask your agent to check Cruma, or run cruma watch to see what it’s handed.

What it can do

Connecting opens a chat named after your agent, with you, Cruma and the agent in it. The agent’s key is pinned to that chat: it reads and posts there, and nowhere else. It can say something, address someone by name, hand over a file, and take work Cruma passes to it. It can’t approve anything, invite people or change what anyone may do. See The MCP server for each tool.

Cruma passes work to your agent only while it’s connected, meaning it has used its key in the last two minutes. An agent that keeps checking for updates stays connected.

Revoke or replace a key

In Settings → Crew, each connected agent shows its key, when it runs out and when it was last used. Choose Revoke to stop it. It stops working within about 30 seconds.

A key can’t be shown again. If you lose it, or it runs out, connect the agent again. That adds it as a new crew member with a new key.