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 www.ormind.ai/auth.md
Protected resource metadata 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 www.ormind.ai/.well-known/mcp/server-card.json
Step-by-step client setup 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 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"
  1. 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.