↻ ricursor

Connect over MCP

Create a workspace and project in Console, then open Connections for your host-specific MCP configuration. The MCP server authenticates with a workspace key (rcsk_…) sent as a Bearer token. Pass your workspace ID and project name when calling its tools; it does not automatically index a repository.

claude mcp add --transport http ricursor https://api.ricursor.com/v1/mcp --header "Authorization: Bearer rcsk_YOUR_KEY"

Context API

Create an API key in Connections. GET /v1/agent/context serves stored constraints and recent state for the key’s workspace. The optional project query is a project name. This is a context API, not an OpenAI-compatible model proxy.

GET https://api.ricursor.com/v1/agent/context?project=YOUR_PROJECT_NAME
Authorization: Bearer YOUR_API_KEY

Memory and reported activity

Add constraints in Console → Elastic memory. Connected agents can report usage and file-change, delta or alert events using ricursor_report or POST /v1/agent/ingest. The Playground guard is a simulation; automatic correction verification and model-request interception are not connected yet.

POST https://api.ricursor.com/v1/agent/ingest
Idempotency-Key: UNIQUE_REPORT_ID
[{"type":"state","project":"YOUR_PROJECT_NAME","kind":"file_change","path":"src/auth.ts","detail":"authGuard added"}]

Guardrails & retry safety

Reports are atomic and tenant-scoped. Reuse the same Idempotency-Key (API) or request_id (MCP) with unchanged data when retrying; changed data with the same ID is rejected. Use a new ID for each new logical report. Batches accept at most 200 events and 256 KiB, real calendar dates, integer tokens up to one billion, and safe relative paths. Named projects must exist; nothing silently falls back to another project. Each workspace accepts 60 new reports per minute; retries of already recorded IDs do not consume this allowance. Receipts persist until the workspace is deleted. These are ingestion safeguards, not an autonomous model safety guarantee.

Success: {"ok":true,"inserted":1,"replayed":false}
Retry:   {"ok":true,"inserted":1,"replayed":true}
Conflict: HTTP 409
MCP: ricursor_report({workspace, project, request_id, usage, state})

API reference

Base address https://api.ricursor.com/v1. Requests and replies are JSON. Errors return {"error": { "code", "message", "requestId" }}. Members of other workspaces get 404; weaker roles get 403.

Agent API

Authorization: Bearer rcsk_… (workspace key)

GET/agent/context?project=NAMEkeySaved constraints and recent state for the key's workspace
POST/agent/ingestkeyReport usage and state events; requires Idempotency-Key
POST/mcpkeyMCP JSON-RPC endpoint (ricursor_context, ricursor_report)

Sign-in

Public, then Authorization: Bearer SESSION

GET/healthpublicBackend status
POST/auth/sign-uppublicCreate an account and personal workspace; returns a session
POST/auth/sign-inpublicEmail + password; returns a session
POST/auth/password-resetpublicRequest a password reset
GET/auth/mesigned inCurrent account
POST/auth/sign-outsigned inEnd this session
POST/auth/sign-out-otherssigned inEnd every other session
POST/auth/passwordsigned inChange password (needs current password)
POST/auth/emailsigned inChange email (needs current password)

Workspaces, team & invites

Authorization: Bearer SESSION

GET/workspacessigned inWorkspaces you belong to
POST/workspacessigned inCreate a workspace (you become owner)
PATCH/workspaces/:wsadminRename
GET/workspaces/:ws/membersmemberList members
POST/workspaces/:ws/membersadminAdd a member
PATCH/workspaces/:ws/members/:useradminChange role (never owner)
DELETE/workspaces/:ws/members/:useradminRemove a member
GET/workspaces/:ws/invitesadminPending invites
POST/workspaces/:ws/invitesadminCreate invite link
DELETE/invites/:idadminRevoke invite
GET/invites/:tokenpublicPreview invite
POST/invites/:token/acceptsigned inAccept once

Projects, memory & keys

Authorization: Bearer SESSION

GET/workspaces/:ws/projectsmemberList projects
POST/workspaces/:ws/projectswriterCreate project
PATCH/projects/:idwriterRename project
DELETE/projects/:idadminDelete project
GET/workspaces/:ws/constraints?project=IDmemberSaved constraints
POST/workspaces/:ws/constraintswriterAdd constraint
DELETE/constraints/:idwriterDelete constraint
GET/workspaces/:ws/projects/:p/constraintswriterConstraints applying to a project
GET/workspaces/:ws/keysadminList workspace keys
POST/workspaces/:ws/keysadminCreate key (secret shown once)
DELETE/keys/:idadminRevoke key

State, activity, usage, AI & CI

Authorization: Bearer SESSION

GET/workspaces/:ws/state?project=IDmemberLive state events
POST/workspaces/:ws/statewriterRecord state events
GET/workspaces/:ws/activitymemberActivity history
POST/workspaces/:ws/activitymemberRecord a switch/recovery entry
GET/workspaces/:ws/usage?project=IDmemberToken usage rows
POST/workspaces/:ws/projects/:p/reviewwriterAI review of changes against constraints
POST/workspaces/:ws/projects/:p/analyzewriterAI CI-log analysis, saved to history
GET/workspaces/:ws/cimemberCI analyses and applied fixes
POST/workspaces/:ws/ci/fixeswriterMark a finding as fixed (once)

Profile & account

Authorization: Bearer SESSION

GET/profilesigned inYour profile
PATCH/profilesigned inUpdate name
GET/preferencessigned inYour preferences
PUT/preferencessigned inSave preferences
PUT/avatarsigned inUpload photo (PNG/JPEG/WebP)
DELETE/avatarsigned inRemove photo
GET/avatars/:usersigned inPhoto of someone you share a workspace with
GET/account/exportsigned inDownload your data
DELETE/accountsigned inDelete account (password + "DELETE")

Staff (administration)

Session + staff role + authenticator code

GET/admin/accessstaffYour staff role and 2FA state
POST/admin/mfa/enrollstaffStart authenticator setup
POST/admin/mfa/verifystaffVerify a 6-digit code
GET/admin/sections/:namestaffRead-only staff section (audited)
GET/admin/accountsstaffAccount directory
POST/admin/accountsowner + recent 2FAChange an account's name or plan
GET/admin/cistaffCI trends across workspaces