# Ormind for agents and developers

Ormind exposes a member's dossiers to AI agents through one Model Context Protocol (MCP) server. An agent connected with a member's account works in their dossiers with exactly that member's rights: what they can read, it can read; what they cannot, it cannot see. Every call is traced in the dossier journal in the member's name.

Ormind has no separate REST API for third parties: the MCP server is the integration surface.

## Endpoint

| | |
|---|---|
| MCP server | `https://app.ormind.ai/api/mcp` |
| Transport | Streamable HTTP, POST only: one JSON-RPC message per request, JSON response. GET and DELETE return 405 (no server stream, no session to close) |
| Server name | `ormind` |
| Authentication | OAuth 2.1 bearer token (Claude.ai, ChatGPT) or a personal agent token `cg_...` (Claude Code, other clients). See https://www.ormind.ai/auth.md |
| Protected resource metadata | https://app.ormind.ai/.well-known/oauth-protected-resource/api/mcp (RFC 9728) |
| Scopes | `workspace:read`, `workspace:write` |
| Rate limit | 60 requests per minute per connection. Over the limit: HTTP 429 with `Retry-After: 1` |
| Server card | https://www.ormind.ai/.well-known/mcp/server-card.json |
| Step-by-step client setup | https://www.ormind.ai/connect.html |

A request without a token gets HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="..."`, which MCP clients follow to start the OAuth sign-in.

## Quick start with Claude Code

1. Sign in at https://app.ormind.ai and open your connections (`https://app.ormind.ai/?connections=1`).
2. Under "With Claude Code on your computer", generate your agent token. It is shown once; regenerating it revokes the previous one.
3. Add the server:

```
claude mcp add --transport http ormind https://app.ormind.ai/api/mcp \
  --header "Authorization: Bearer cg_your_token"
```

4. In Claude Code, type `/mcp`: Ormind is listed as connected, with its tools. Then ask: "List my workspaces."

Any MCP client that speaks Streamable HTTP (Codex, Cursor, VS Code and others) uses the same address and the same `Authorization: Bearer` header.

## Concepts

- **Workspace (dossier):** one project with its own members and roles. Members call them dossiers; tools call them workspaces and take a `workspace` argument (its identifier).
- **Zones:** `raw/` holds the sources (documents, never modified), `raw/_inbox` receives new deposits, `wiki/` holds the compiled knowledge, `output/` holds deliverables, `db/` holds sqlite databases, `tools/` holds workspace scripts.
- **Roles:** reader, editor, owner. A reader's agent never sees the writing tools. With the `workspace:read` scope, writing tools are hidden too.
- **Journal:** `log.md` records who did what and when, including every agent call.

## Main tools

The live list comes from `tools/list`, filtered by the member's rights. Every tool has a JSON Schema for its input and `readOnlyHint`, `destructiveHint` and `idempotentHint` annotations.

| Tool | What it does | Read only |
|---|---|---|
| `list_workspaces` | Lists the member's workspaces with identifier, title and role. Call it first | Yes |
| `list_files` | Lists files and folders of a workspace directory | Yes |
| `read_file` | Reads a wiki page, a source or a deliverable (PDF with OCR, images, emails, Word and Excel files) | Yes |
| `search` | Full-text search across the wiki, sources and deliverables | Yes |
| `query_table` | Read-only SQL (one SELECT) on a workspace sqlite database | Yes |
| `list_deliverables` | Lists everything produced under `output/` | Yes |
| `read_journal` | Reads the workspace journal, last lines first | Yes |
| `create_workspace` | Creates a workspace owned by the member | No |
| `deposit` | Drops a document in the inbox; never replaces a file | No |
| `write_file` / `patch_file` | Writes a page, or applies exact patches with conflict detection | No |
| `record_declaration` | Files a fact the member states in chat as a dated, immutable source | No |
| `archive_deposit` | Files an inbox deposit under `raw/` | No |
| `begin_changeset` ... `commit_changeset` | Stages several writes and publishes them in one atomic commit, or not at all | No |
| `export_workspace` | Exports a whole workspace as a re-importable archive (owner only) | No |

Other tools cover tasks, calendar suggestions, database inspection, ingestion tracking and workspace tools run in an isolated sandbox.

## Results and errors

- Tool results are text or JSON; pages and deliverables can also render as MCP Apps panels (`ui://` resources) in hosts that support them, such as Claude.
- Invalid methods, unknown tools and bad arguments return structured JSON-RPC errors with a `code` and a `message`.
- A permission refusal starts with `⛔ BLOCKED`. It is final: do not retry, tell the member.
- `patch_file` answers `CONFLICT` and writes nothing when the page changed since it was read. Read it again, then patch.
- Retrying is safe where it matters: `deposit` never overwrites (a taken name gets a suffix), and a changeset is published in one commit or not at all.

## Support

Questions about integrating: contact@ormind.ai. Problems with an account: support@ormind.ai.