MCP reference

Overview

The data model in one breath: a bundle is a folder of concepts; a concept is a markdown document at a path such as auth/token-expiry, with type, tags, relations and a rev. Links in the web app are relations here. See the manual for the rest.

Endpoint

https://mcp.fra.korpus.cloud/mcp

• JSON-RPC over POST to /mcp; each request stands alone, so there is no stream to open with GET and no session to end. The token decides the agent; the consent screen lets the person pick it.
• https://mcp.fra.korpus.cloud/mcp/<agent> signs in as that agent, preselected on the consent screen. A token issued for another agent is refused with agent_mismatch, which names the right URL.
• An account lives in the region it signed up in; this endpoint serves Frankfurt accounts.

Connect a client

Claude

As yourself (me): Korpus is listed in Claude's connector directory. Settings → Connectors, search for Korpus, choose Connect, sign in and keep me. Often quicker: Add custom connector, name it Korpus, paste https://mcp.fra.korpus.cloud/mcp/me. It also works in Claude for desktop and mobile; turn it on per chat from the tools menu.

As an agent with rules: add it as its own connector, not through the directory entry. claude.ai → Settings → Connectors → Add custom connector, name it korpus-<agent>, paste https://mcp.fra.korpus.cloud/mcp/<agent>. A connection of its own holds only that agent's rules, so it does its job and nothing else.

Claude Code

claude mcp add --transport http korpus https://mcp.fra.korpus.cloud/mcp

Then run /mcp and sign in.

ChatGPT

Settings → Apps & Connectors → Advanced, turn on Developer mode, then Create. Name it Korpus, paste the URL.

Any other client

{
  "mcpServers": {
    "korpus": {
      "type": "http",
      "url": "https://mcp.fra.korpus.cloud/mcp"
    }
  }
}

This is the .mcp.json shape Claude Code and similar clients read; others ask only for the URL. The server name is yours to choose. For an agent with rules, use /mcp/<agent> and name the server korpus-<agent>. The web app's Link an app and the get_agent_connect tool print these lines for you.

Authentication

A client with MCP OAuth support needs nothing configured: it discovers everything from the first 401.

1. Discovery. An unauthenticated request answers 401 with WWW-Authenticate: Bearer resource_metadata="https://mcp.fra.korpus.cloud/.well-known/oauth-protected-resource" (RFC 9728). Authorization server metadata is at /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/openid-configuration.
2. Registration. POST /oauth/register (RFC 7591). Public clients only: token_endpoint_auth_method must be none. Redirect URIs must be https, or http on localhost, 127.0.0.1 or [::1]. Registrations expire after 90 days.
3. Authorize. GET /oauth/authorize with response_type=code, PKCE S256 and scope mcp. The person signs in to the web app, picks the agent the client acts as (me, an existing one, or a new one) and presses Allow. The request is good for 10 minutes; the code for 5.
4. Token. POST /oauth/token with authorization_code or refresh_token. The access token lives 1 hour, the refresh token 30 days. Refresh tokens rotate on every use; one presented twice revokes the whole grant.

Each approval is a grant, listed under its agent on the web app's Agents page. Disconnect there ends it at once; the next call answers 401. Deleting the agent ends all of its grants.

Instructions

On initialize the server sends instructions a client passes to its model:

1. Which Korpus deployment the client reached.
2. A short overview: the data model, which tools only look, the change description every write carries, how to find things (list_folder first), how usage is metered.
3. The person's plan, free or Plus. Every tool works on either; only the limits differ.
4. The agent's name and job, and for an agent with rules, the rules.

Everything longer sits behind the manual tool, so a client that drops the instructions can still read them. Topics:

Tools

One tool per action, each with a title a client shows and hints it sorts by. The reading tools carry readOnlyHint, so most clients let a person allow them for good; every other tool asks, and the ones that remove or end something also carry destructiveHint. Every tool is openWorldHint: false. An agent with rules gets no managing tool at all.

• Change descriptions. create_concept, update_concept, delete_concept, add_relation and remove_relation take a required change_description: one line, what changed and why. It is the log; nothing else records why a concept moved.
• Index and log. Every folder has an index (read_index: the titles and descriptions of its concepts) and a log (read_log: its changes, newest first). Both are generated from the content as OKF 0.2 §8 and §9 describe, never stored, so no concept may be named index or log.
• Revisions. read_concept returns a concept's rev. Pass it back on update_concept and the call fails with rev_mismatch if someone changed the concept meanwhile. Without it the update lands and says whose revision it changed. update_concept changes only the fields given; "" clears a text field.

On the wire

A tool call is an ordinary tools/call. Its answer is a tool result: the first content item is plain text, followed by up to 50 resource_links to the concepts it names. There is no structuredContent.

POST /mcp
Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": { "name": "create_concept", "arguments": {
    "bundle": "01M3…", "path": "README",
    "type": "Guide", "title": "Research",
    "body": "# Research\nWhat this bundle is for.",
    "change_description": "Said what this bundle is for" } } }

200 OK
{ "jsonrpc": "2.0", "id": 7, "result": {
  "isError": false,
  "content": [
    { "type": "text", "text": "ok README created, rev 1" }
  ] } }

A call that fails answers the same way with isError: true and the text <code>: <message>. Only transport and account problems are JSON-RPC or HTTP errors: 401 without a valid token, 403 for a token of another agent (-32003 agent_mismatch) or a blocked account (-32003 account_blocked).

Every tool

Parameters with ? are optional. The input schemas (tools/list) carry the same fields with a description each; the manual topics explain the behaviour.

Field shapes

Reading readOnly · idempotent · every agent

Writing asks · every agent, inside its rules

Managing asks · me agent only

Resources and prompts

Both are text/markdown and go through the same access checks as the tools.

Agents and rights

Every token belongs to one agent, and every write is stamped with it: @you via <agent>.

• me is built in, fixed and holds the person's full rights. Nothing creates, changes or deletes it.
• Other agents carry a job and rules. At most 50 agents per account, 50 rules each; names are 1–32 characters of a-z 0-9 . _ -.

Rules

{ "bundle": "<id> | *", "path": "<pattern>", "rights": ["create", "read", "update", "delete"] }

• read is always implied.
• Patterns: * alone is the whole bundle; * or ** as the last segment is everything below that folder, at any depth (the two mean the same there); ** elsewhere is any number of folders; * inside a segment matches within that segment. No .md.
• Rules only subtract: the person's role in the bundle is checked first.
• Rules are read on every request, so a change holds from the next call.

An agent with rules never gets create_bundle, create_relation_type, invitations, get_agent_connect or agent management. A refusal answers restricted and names what the agent may do instead; get_rights asks in advance.

Errors

A failure reads <code>: <message>, sometimes followed by details as JSON and a pointer to a manual topic. The message names the fix.

More codes

Retry hints: rate_limited carries retry_after, bundle_not_ready and bundle_busy carry retry_after_seconds, all in seconds. A new bundle is ready within 60 seconds; retry every 10. For session and week limits the wait can be hours: stop and tell the person. manual topic=errors explains every code.

Limits and usage

Usage is metered by what a call costs to serve. Writes and reads each have a short-term rate, and every call spends from a 5-hour session and a weekly allowance: a read counts 1, a write 3, a body search 10. Over a limit, the call answers rate_limited with retry_after. The allowances differ by plan (free or Plus) and are not published; get_usage shows how full each one is, and is never refused. Space is counted per person, over the bundles they created.

Not on MCP

Publishing to the catalog, using a template, admin screens for Korpus staff and billing are in the web app only. Questions: support@korpus.cloud.