MCP & AI integrations

import { Aside } from ‘@astrojs/starlight/components’;

The Model Context Protocol (MCP) lets AI assistants read and (with the right API key scopes) update your team knowledge base through tools such as search, list documents, and create/update document.

Orimora ships two MCP transports:

1. HTTP endpoint at /api/mcp — recommended for remote access. Uses the MCP Streamable HTTP transport. Authenticate with an API key as Bearer token.
2. stdio server in the repository — for local development. You point your MCP client at yarn mcp.

Prerequisites

• Same stack as Installation: Node.js, Yarn, PostgreSQL, and a working .env with at least DATABASE_URL (and the other required secrets described there).
• An API key from the web app: Settings → Developers. Copy the full token once (format kb_…). The MCP server validates it against the database like the REST API.

Treat `ORIMORA_API_KEY` like a password. Anyone with the key and database access can act as that key’s team user within the key’s scopes.

Option 1: HTTP endpoint (recommended)

The HTTP endpoint is available at {APP_URL}/api/mcp (for example https://your-domain.com/api/mcp) and must be enabled per team in Settings → Developers → MCP Server (HTTP). Only team admins can toggle MCP.

Authentication uses Bearer tokens — the same API keys from Settings → Developers.

Quick start (Cursor + hosted Orimora)

1. In the web app, go to Settings → Developers and turn on MCP Server (HTTP).
2. Under API keys, create a key with the scopes you need (write if tools should create or edit documents). Copy the full token once — it starts with kb_.
3. Use the Copy endpoint URL and Copy Cursor MCP JSON buttons on the same page (they appear when MCP is enabled). In the JSON, replace YOUR_API_KEY with your real kb_… token.
4. Merge the mcpServers entry into Cursor’s MCP config:
   • All projects (user): ~/.cursor/mcp.json on macOS/Linux, or the path shown in Cursor Settings → MCP for your OS.
   • Single repository: .cursor/mcp.json at the repo root.
5. Restart Cursor or use Reload MCP / restart the MCP host so the new server is picked up.

The Developers page always uses your deployment’s real `APP_URL` for the endpoint, so you do not have to guess the host. If copy-to-clipboard is blocked by the browser, select the JSON manually and copy it.

Cursor (HTTP) — config snippet

{
  "mcpServers": {
    "orimora": {
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace https://your-domain.com with your instance URL and YOUR_API_KEY with the full kb_… key.

Claude Desktop (HTTP)

Use the same URL and Bearer token. Claude Desktop supports HTTP MCP servers natively since late 2025.

Any MCP client

Send standard MCP Streamable HTTP requests:

• POST /api/mcp — MCP JSON-RPC messages
• GET /api/mcp — SSE stream for server-initiated messages
• DELETE /api/mcp — session cleanup

All requests require the Authorization: Bearer kb_… header.

The HTTP endpoint is **stateless** — each request creates a fresh MCP session. This keeps the server simple and works well with load balancers.

Option 2: stdio server (local development)

For local development with direct database access, you can use the stdio transport:

export ORIMORA_API_KEY="kb_your_full_token_here"
yarn mcp

The process uses stdio — it is meant to be spawned by an MCP client, not browsed in a browser.

Under the hood this runs tsx with tsconfig.mcp.json and src/mcp-server/index.ts (see the mcp script in package.json).

Cursor (stdio)

{
  "mcpServers": {
    "orimora": {
      "command": "yarn",
      "args": ["mcp"],
      "cwd": "/absolute/path/to/orimora-repo",
      "env": {
        "ORIMORA_API_KEY": "kb_…",
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
      }
    }
  }
}

• cwd must be the Orimora repo root so dependencies and path aliases resolve.
• If your client loads .env for you, you may omit duplicate variables — otherwise pass DATABASE_URL explicitly.

Claude Desktop and others (stdio)

Use the same pattern: command + args + working directory + environment with ORIMORA_API_KEY and DATABASE_URL.

Permissions and restricted mode

API keys support:

• Scopes: read, write, admin — MCP tools that mutate content require write where applicable.
• Restricted mode: optional allowlists per collection and per-document overrides, configured in the app under Settings → Developers → Configure access. The same rules apply to MCP and to /api/v1/.

Related documentation

• REST API overview — Bearer kb_… authentication for HTTP clients
• Configuration — environment variables
• OpenAPI reference — REST operations

For a short maintainer checklist (dev server URL, health check, internal notes), see internal/dev-and-mcp.md in the repository.