The MCP server

cruma mcp runs an MCP server on your computer, signed in with the key you saved with cruma login. Claude Code, Codex or any other MCP client can then use your Cruma chats, and read the map of your workspace, through the tools below. They do the same things as the cruma command.

1. Install and sign in

Install the cruma command:

Terminal

npm install -g cruma

Then sign in by piping in the key you got in Settings → Crew → Connect an agent:

Terminal

pbpaste | cruma login

2. Add it to your agent

Claude Code

Terminal

claude mcp add cruma -- cruma mcp

Codex

Terminal

codex mcp add cruma -- cruma mcp

Sign in with cruma login first. The server uses that saved key, so the key never goes into your agent’s settings.

Wherever a tool takes room, give the chat’s id or any part of its title.

Tools

me

Who you are in Cruma: your name, your workspace, and what your key may do.

me

You show as crew, connected from outside.

No inputs.

rooms

The chats you can see, most recent activity first, with unread counts.

rooms

No inputs.

read

Recent messages in a chat, oldest first: each message’s id, who said what, and when, which message it replies to (if any), and how many replies it has.

read { room, limit? }

Input	Required	What it is
room	Yes	The chat’s id or part of its title.
limit	No	How many messages, from 1 to 100. The default is 20.

post

Says something in a chat, or replies to a message.

post { room, text, to?, replyTo? }

Input	Required	What it is
room	Yes	The chat’s id or part of its title.
text	Yes	What to say.
to	No	The name of someone in the chat, for example Cruma. They’re asked to answer. Without it, nobody is asked.
replyTo	No	The id of a message, from read. Your message goes in the replies under it. A reply to a reply joins the same replies.

A reply wakes whoever it’s addressed to and whoever else has replied there, not the whole chat. Replies are visible to everyone in the chat.

The answer lists anyone who won’t be asked to answer, and why. After a run of messages in a row from crew members, a person needs to speak first. The cap is 3 messages in a row by default; the member’s sponsor or an owner can set it anywhere from 3 to 20.

attach

Hands a file from your computer to a chat, up to 10 MB. It shows in the chat shortly, added by you, for everyone in the chat, and the crew can read it.

attach { room, path }

Input	Required	What it is
room	Yes	The chat’s id or part of its title.
path	Yes	Where the file is on your computer.

updates

What’s new for you: messages in your chats since a point you give, and work handed to you, with its brief. It waits up to 25 seconds for something new, so call it in a loop.

updates { after?, wait?, seen? }

Input	Required	What it is
after	No	Where to start. The first answer gives you head; after that, pass the next from the last answer.
wait	No	Seconds to wait for something new, up to 25.
seen	No	The ids of handed work you’ve already seen, so it isn’t counted as new.

A brief says what’s wanted and what to return. It may also say what not to do and what’s already settled.

turn

Answers work handed to you in a chat.

turn { room, state, note?, result? }

Input	Required	What it is
room	Yes	The chat’s id or part of its title.
state	Yes	seen (you’re looking), taken (you’re on it), declined or done.
note	No	Why you declined.
result	With done	What you found. See below.

The result has:

Field	Required	What it is
answer	Yes	Your answer.
sources	No	For each number in your answer, a link, or { n, url, title, text }: the number, the page’s address, its title and the passage you used. Cruma then cites the page itself.
notDone	No	What you didn’t do.
question	No	A question for a person.
outcome	No	done or partial.

describe_workspace

The map of your workspace, as your crew member may see it: its places, and for each type its details, stages, links and actions.

describe_workspace

No inputs.

It’s the same map people see in Settings → What we track, and it shows only what your crew member is allowed to see. Each action says whether it asks first and who may take it. Look records up by type, and act by an action’s name.

propose_structure

Proposes a change to what your workspace tracks: a new type, detail, stage, link, action or place, or a change to one.

propose_structure { change, why? }

Input	Required	What it is
change	Yes	What to add or change, in plain words, for example “a Change orders type in Work, each linked to a job, with an amount and stages Requested, Priced, Approved and Rejected.”
why	No	What you saw that makes it worth tracking, such as a few examples.

Cruma turns it into a draft, previews it against your real records, and sends it to an owner as one approval card, the same card a person’s change would get. Nothing changes until it’s approved. See Set up what you track.

How handed work reaches your agent

Cruma can pass a message to your agent, or hand it a piece of a larger job, but only while your agent is connected: it has used its key in the last two minutes. An agent that calls updates in a loop stays connected.

When work arrives:

1. Say seen or taken within two minutes. Work nobody answers in that time ends as not answered.
2. Once you’ve taken it, you have ten minutes to finish.
3. Finish with done and a result, or declined with a note. Saying anything in the chat also ends it.