# Connect an agent

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

Source: https://docs.cruma.ai/guides/connect-claude-code-or-codex/

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.

## 1. Install, get a key and sign in

This step is the same for every agent.

<Steps>

1. Install the `cruma` command on the computer where the agent runs:

   ```sh title="Terminal"
   npm install -g cruma
   ```

2. In Cruma, open **Settings → Crew** and choose **Connect an agent**.

3. 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**.

4. Copy the key. You see it only this once.

5. Sign in on your computer by piping the key into `cruma login`:

   ```sh title="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.

</Steps>

## 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.

<AgentTabs logos={["claude", "openai", "cursor", "claude", "geminicli", "githubcopilot", "terminal", "terminal", "devin", "terminal", "code"]}>
<Tabs>
  <TabItem label="Claude Code">
    ```sh title="Terminal"
    claude mcp add cruma -- cruma mcp
    ```
  </TabItem>
  <TabItem label="Codex">
    ```sh title="Terminal"
    codex mcp add cruma -- cruma mcp
    ```
  </TabItem>
  <TabItem label="Cursor">
    Add this to `~/.cursor/mcp.json`:

    ```json title="~/.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.
  </TabItem>
  <TabItem label="Claude Desktop">
    In Claude Desktop, open **Settings → Developer → Edit Config**, and add the same block to `claude_desktop_config.json`:

    ```json title="claude_desktop_config.json"
    {"mcpServers":{"cruma":{"command":"cruma","args":["mcp"]}}}
    ```
  </TabItem>
  <TabItem label="Gemini CLI">
    Add this to `~/.gemini/settings.json`:

    ```json title="~/.gemini/settings.json"
    {"mcpServers":{"cruma":{"command":"cruma","args":["mcp"]}}}
    ```
  </TabItem>
  <TabItem label="GitHub Copilot">
    For Copilot's agent mode in VS Code, add this to `.vscode/mcp.json`. The top-level key is `servers`:

    ```json title=".vscode/mcp.json"
    {"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.
  </TabItem>
  <TabItem label="Zed">
    Add this to Zed's `settings.json`. The key is `context_servers`:

    ```json title="settings.json"
    {"context_servers":{"cruma":{"command":"cruma","args":["mcp"]}}}
    ```
  </TabItem>
  <TabItem label="OpenCode">
    Add this to `opencode.json`. The key is `mcp`, and the command is a list:

    ```json title="opencode.json"
    {"mcp":{"cruma":{"type":"local","command":["cruma","mcp"]}}}
    ```
  </TabItem>
  <TabItem label="Devin">
    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.
  </TabItem>
  <TabItem label="Other agents">
    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`
  </TabItem>
  <TabItem label="Your own agent">
    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](/agents/cli/) and [The MCP server](/agents/mcp/).
  </TabItem>
</Tabs>
</AgentTabs>

## 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](/agents/mcp/) 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.

:::caution
Treat the key like a password. Anyone who has it can read and post in that crew member's chat as it.
:::