Ork MCP Server

Let AI agents read and write your Ork notes.

ork-mcp is a Model Context Protocol server. It exposes your Ork notes — search, create, append, tag, publish, organize — as tools any MCP-capable client (Claude Desktop, Claude Code, Cursor, …) can call on your behalf.

Contents

• What is MCP?
• Install
• Authentication
• Connect a client
  • Claude Desktop · Claude Code · Cursor · Hosted MCP (Claude.ai / ChatGPT) · MCP Inspector
• Tools reference
• Example prompts
• Engineer Brain
• Security model
• Troubleshooting

What is MCP?

MCP is an open standard for connecting AI assistants to external tools and data. Instead of every app building a bespoke integration, it exposes one MCP server and any MCP-capable client can use it.

• Server — exposes capabilities (this: ork-mcp).
• Client — the host app the model runs in (Claude Desktop, Cursor, …).
• Tools — callable functions with JSON schemas the model invokes.

The client launches the server as a subprocess (stdio) and the model decides when to call each tool, based on the tool’s description. You never type tool calls — you just talk to your agent.

You ──▶ Agent (Claude) ──▶ MCP tool ──▶ ork-mcp ──▶ Ork API
                                                       │
You ◀── phrased answer ◀── tool result ◀──────────────┘

Install

Clients launch it with no install via npx:

{ "command": "npx", "args": ["-y", "@ork.so/ork-mcp@latest"] }

From source

# from the monorepo root (Node >= 22)
pnpm --filter @ork.so/ork-mcp build
ln -sf "$PWD/apps/mcp/dist/index.js" /opt/homebrew/bin/ork-mcp   # put on PATH
ork-mcp --help   # (it runs as a stdio server; see clients below)

Authentication

The server reads auth from its environment — there is no interactive login.

Get an API key

Via the CLI:

ork token create "Claude agent"     # prints the key once — copy it

Via the web app: Profile → API Keys → Create (the key is shown once).

🔐 Prefer an API key over a session token for agents: it’s scoped, independently revocable, and doesn’t expire. Revoke any time with ork token revoke <id> or from the web UI.

Connect a client

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ork": {
      "command": "ork-mcp",
      "env": {
        "ORK_API_KEY": "ork_…"
      }
    }
  }
}

Fully quit (⌘Q) and reopen Claude Desktop. The Ork tools appear in the tools menu. Then just ask: “List my recent Ork notes.”

Claude Code

Plugin (recommended) — installs the server and the Engineer Brain skill, and prompts for your key (stored securely, no config editing):

/plugin marketplace add Ork-so/ork-plugin
/plugin install ork@ork-so

Manual — server only:

claude mcp add ork --env ORK_API_KEY=ork_… -- ork-mcp
claude mcp list      # verify

Cursor

Cursor speaks MCP but can’t install Claude Code plugins. The plugin repo’s cursor/ folder has ready-to-import files so there’s no JSON to hand-write:

• One-click — the “Add to Cursor” deeplink in that folder’s README.
• By config — copy cursor/mcp.json to ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per project), same shape as Claude Desktop, then paste your key.

For the Engineer Brain behavior, also copy the rule file from that folder into your project’s .cursor/rules/.

Hosted MCP (Claude.ai / ChatGPT)

Desktop clients use stdio (above). Browser / remote hosts need Streamable HTTP at:

https://mcp.ork.so

Claude custom connector (recommended):

1. URL: https://mcp.ork.so
2. Authentication: Sign in (OAuth)
3. OAuth client: Use Claude’s published identity (CIMD)
4. Transport: Streamable HTTP
5. Approve on ork.so when prompted — Ork mints a revocable API key for that connector

API key (no OAuth): header Authorization: Bearer ork_… or x-api-key: ork_… (Claude → Request headers → No sign-in, or Cursor mcp.json headers).

Health: https://mcp.ork.so/health
Discovery: https://mcp.ork.so/.well-known/oauth-authorization-server

MCP Inspector (testing)

The fastest way to test the server in isolation — a UI to list and call tools:

npx @modelcontextprotocol/inspector \
  -e ORK_API_KEY=ork_… \
  ork-mcp

Open the printed URL, click Connect → List Tools, then run any tool with a form.

Tools reference

21 tools, grouped below. Each shows its parameters (? = optional).

Read

Write

Tags

Publishing

Collections

Boards

Call get_board before edit_board so you can refer to cards by id. Edits replace the board’s saved layout, so if you have the board open in Ork, reload it after the agent finishes rather than editing at the same time.

🛡️ There is intentionally no delete tool — agents can’t destroy notes or boards, and edit_board only adds to a board.

Tool input is validated with JSON Schema, and errors (e.g. a missing/expired key) come back as readable, model-facing messages.

Example prompts

Once connected, talk naturally — the agent picks the right tool:

• “What did I note about the Postgres migration?” → search_notes
• “Summarize this article and save it to Ork tagged #reading.” → create_note + add_tags
• “Add these three action items to my standup note.” → append_to_note
• “What did I write this week?” → list_notes
• “Publish my ‘Q3 plan’ note and give me the link.” → publish_note
• “Group my launch notes into a ‘Launch’ collection.” → create_collection + add_to_collection
• “Sketch a launch-plan board with the key steps and how they connect.” → create_board
• “Add a ‘risks’ checklist to my launch board and link it to the plan.” → get_board + edit_board

Engineer Brain

The Claude Code plugin bundles engineer-brain, a skill that turns these tools into a persistent project memory. It reads a project’s Ork collection at the start of a session, and auto-records decisions, architecture, structure changes, and gotchas as atomic, tagged notes while you work — searching first so it updates existing notes rather than duplicating them.

Point it at a collection with one line in your project’s AGENTS.md or CLAUDE.md:

Ork Engineer Brain collection: "My Project"

If the line is absent, the agent asks the first time it needs it. Say “update the brain” to force a write. Cursor users get the same behavior via the rule file in the plugin repo’s cursor/ folder.

Security model

• Scoped keys. Each agent uses its own API key — revoke one without affecting the others or your session.
• No destructive tools. No delete; publishing is reversible.
• Your data path. Tools call the same authenticated Ork API as every other client; notes stay encrypted at rest server-side.
• stdout is the protocol channel. The server logs only to stderr, so tool transport is never corrupted.

Troubleshooting

_{See also: Ork CLI — the same capabilities for humans at the terminal.}