# @monnet/mcp

Model Context Protocol (MCP) server for Monnet.

Exposes motions, plans, and approvals to MCP-compatible clients (Claude Desktop, Cursor, etc.) so you can work with your Monnet workspace from your terminal without leaving your AI assistant.

## Install

Install the Monnet MCP and the `/monnet-init` onboarding command for Codex and
Claude Code:

```bash
npx -y @monnet/mcp install
```

Quit your coding agent completely and reopen it — a new session inside the
running app does not pick the server up — then run `/monnet-init` on Claude
Code, or `$monnet-init` on Codex, where it is installed as a skill. The
command opens a browser for signup/sign-in and prints a short code you type
there — that code, not the link, is what
authorizes the connection, so never enter one someone else sends you.

From there the flow reads where you actually are: it picks up a workspace you
have already been invited to, or stands a new one up. A new workspace is set up
for one workflow — taking in product ideas — so that an idea raised in Slack or
Teams reaches Monnet and gets scoped and routed for approval. That means the
intake playbook, the pages that let Monnet judge an idea, and the integration.
It ends with one coworker to test it with and the message to send them.

Want it set up differently? Type your instructions after the command
(`/monnet-init we're an agency, set up intake for client requests`) and the
flow adjusts to them.

Progress is saved locally, so rerunning the command safely resumes an
interrupted setup.

### Uninstall

```bash
npx -y @monnet/mcp uninstall
```

Removes the MCP registration from Claude Code and Codex, the `monnet-init`
command and skill, and the credential saved on this machine, and revokes that
credential's API key. If the key cannot be revoked from there, the command
says so and points at Settings → Monnet MCP.

### Manual MCP configuration

Add this to your MCP client config (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json` for Claude Desktop):

```json
{
  "mcpServers": {
    "monnet": {
      "command": "npx",
      "args": ["-y", "@monnet/mcp"],
      "env": {
        "MONNET_API_KEY": "mnk_..."
      }
    }
  }
}
```

Generate an API key from the Monnet web app: Settings → Monnet MCP → Generate new key
(<https://app.monnet.ai/?settings=features.mcp>).

## Environment variables

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `MONNET_API_KEY` | no | credential saved by `monnet init` | Bearer token (`mnk_*`), sent as `X-API-Key` header on every request |
| `MONNET_API_URL` | no | `https://api.monnet.ai` | Override for self-hosted or local dev backends |

## Local development

```bash
cd mcp-server
npm install
npm run build
```

Point your MCP client at the local build:

```json
{
  "mcpServers": {
    "monnet": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "MONNET_API_KEY": "mnk_...",
        "MONNET_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

Restart Claude Desktop / Cursor after editing the config.

## Tools

**Connection**

- `monnet_whoami` — verifies the connection and lists the API keys on your account.
- `list_workspaces` — the workspaces you belong to, with the slug every other tool takes.

**Motions**

- `get_motion` — one motion in full: body, plan, members, comments, and its attached files.
- `read_motion_file` — an attachment's contents. Text and source files come back as
  themselves, Word/Excel/PowerPoint as their extracted text, images as the image. A PDF
  cannot be read this way — you get its URL to open instead.
- `list_motions` — what exists.
- `get_inbox` — what is waiting on you, split into `priority` (a step assigned to you) and
  `active` (everything else you follow). Every workspace unless one is named.
- `create_thread` — open a pre-motion conversation from a free-form prompt.
- `update_motion`, `comment`, `approve`, `reject` — write paths.
- `ask_monnet` — ask Monnet itself, in your private channel on a motion.

**Playbooks**

- `list_playbooks` — the instructions a workspace has written for Monnet, one per recurring
  workflow. Names and descriptions only.
- `read_playbook` — one of them in full, body included. Read before you revise: an edit
  replaces the field it is given, so a revision written from memory drops the rest.
- `create_playbook`, `edit_playbook` — write and revise them, for workspace owners and admins.
  A playbook changes how Monnet handles that workflow for the whole team, so show the draft
  first. Both are ordinary writes: the team can reopen and rewrite a playbook in the workspace
  settings at any time.

**Company brain**

- Read: `get_wiki_schema`, `get_wiki_tree`, `read_wiki_page`, `search_wiki`.
- Write: `create_wiki_page`, `edit_wiki_page`, `create_wiki_folder`, `rename_wiki_folder`,
  `move_wiki_node`, `delete_wiki_page`, `delete_wiki_folder`.
- Sources: `list_wiki_sources`, `read_wiki_source`, `push_wiki_source`,
  `mark_wiki_source_ingested`, `requeue_wiki_source`, `delete_wiki_source`.

## Approval gate on send actions

Tools that send a message under your identity (`comment`) or destroy something
(`delete_wiki_page`, `delete_wiki_folder`, `delete_wiki_source`) never dispatch
automatically. Before the message leaves the MCP server, your client
shows a confirmation dialog (MCP elicitation) with a preview of the message;
nothing is sent unless you explicitly approve. If your MCP client does not
support elicitation, the send is aborted — the gate fails closed.

That last sentence is the reason the list is short. A gated tool does not
degrade on a client that cannot elicit, it stops — so the gate is reserved for
what is genuinely unrecoverable, and ordinary writes stay ordinary.