Rakontevr Integration
Full integration map — SDK, Shield, MCP, Gateway, BuilderHub, and Iorek
Rakontevr Integration
CleverCase V2 is a standalone tenant client of the Rakontevr platform. The two codebases communicate only through authenticated HTTP channels — no workspace imports, no shared monorepo paths.
This page maps every integration surface: SDK, Shield, MCP, Gateway, BuilderHub, and Iorek.
Integration map
Approved integration channels
| Channel | Direction | Auth | Purpose |
|---|---|---|---|
| RSP Gateway | CleverCase → Rakontevr | RAKONTEVR_SERVICE_KEY | Inference, chat completions |
@rakontevr/sdk (vendored) | CleverCase → Rakontevr | Same service PAT | Telemetry |
| BuilderHub telemetry | CleverCase → Rakontevr | Same service PAT | App usage metering |
Iorek /v1/iorek/ask | CleverCase → Rakontevr | Same service PAT | Gladys legal Q&A |
| CleverCase REST API | Rakontevr → CleverCase | RAK_CLEVERCASE_SERVICE_KEY | Platform callbacks |
| MCP tools | Cursor → Rakontevr | MCP env + PAT | Stories, AI, docs, health |
Forbidden: importing Rakontevr platform source, calling localhost:1234 LM Studio directly, hardcoding internal URLs outside .rakontevr/tenant.json.
Environment variables
Provisioned by rak client provision-full --client clevercase:
| Variable | Purpose |
|---|---|
RAKONTEVR_SERVICE_KEY | PAT for Gateway / BuilderHub / Iorek |
RAKONTEVR_GATEWAY_URL | Gateway base (default: https://gateway.rakontevr.ai/v1) |
RAKONTEVR_TENANT_ID | 00000000-0000-4000-a000-000000000003 |
RAK_TENANT_ID | Same UUID — MCP and RSP attribution |
RAK_TENANT_SLUG | clevercase |
NEXT_PUBLIC_RAKONTEVR_APP_ID | BuilderHub app registration |
Setup in this repo:
clevercase setup # writes .cursor/mcp.json + session
clevercase whoami # verify service key + tenant
rak client verify-access --email you@clevercase.com --tenant clevercaseSDK layer
Vendored at vendor/rakontevr/sdk/. Used for telemetry only — not platform business logic.
Key files:
| File | Role |
|---|---|
src/lib/clevercase/platform/with-cc-api.ts | JSON route wrapper + telemetry |
src/lib/clevercase/platform/with-cc-api-stream.ts | SSE wrapper (Gladys) |
src/lib/clevercase/rakontevr-config.ts | Server-side gateway config |
src/lib/clevercase/rakontevr-client.ts | HTTP client helpers |
src/middleware.ts | x-cc-trace-id ↔ X-Trace-Id bridge |
Gateway
All AI inference routes through the RSP Gateway — including Cursor BYOK chat (taskType: cursor-gateway).
Gateway URLs:
| Environment | URL |
|---|---|
| Hosted (default) | https://gateway.rakontevr.ai/v1 |
| Tailscale internal | Team-specific (e.g. http://rsp-gateway:4242/v1) |
| Local daemon | http://localhost:4242/v1 |
BuilderHub
BuilderHub registers CleverCase as app app_clevercase with route surface prefix /builderhub/experiences/clevercase.
| Integration | Path / API |
|---|---|
| Unified agent | Gladys → personaId gladys, domain legal |
| Telemetry | Per-route withCcApi reports |
| AppKit surfaces | Business Studio, Agent Studio via src/lib/clevercase/appkit/ |
Required API scopes (from provision-full):
clevercase:read,clevercase:writeinference
Iorek engine
Gladys is a persona on Iorek — not a separate model path.
| Call site | Entry |
|---|---|
| Browser Gladys | /api/gladys/stream → streamGladysAsk |
| MCP legal Q&A | rsp_ask_iorek({ personaId: gladys, domain: legal }) |
| Cursor agents | Same MCP tool with tenant UUID |
Virtual model defaults: iorek (use iorek-v4 for NIM-preferred).
MCP (Cursor thin client)
Client orgs receive a reduced MCP catalog (CLIENT_ORG_MCP_TOOLS):
| Allowed | Blocked (platform-only) |
|---|---|
ai_query, ai_status | dgx_fleet_status, fleet_* |
rsp_stories, rsp_tasks, rsp_run_status | rsp_execute, rsp_plan_and_dispatch |
rsp_check, rsp_audit, rsp_execute_tenant | Deploy / rollback tools |
docs_*, cursor_doctor, gateway_status | rsp_security_scan |
rsp_ask_iorek, business_rules_search | |
workflow_search, secrets_list |
MCP env in .cursor/mcp.json:
{
"RAK_TENANT_ID": "00000000-0000-4000-a000-000000000003",
"RAK_TENANT_SLUG": "clevercase",
"RAK_MCP_PRESET": "client"
}Audit correlation: .rakontevr/logs/mcp-tool-audit.jsonl includes sessionId, tenantId, rspRunId, storyId.
Shield V2
Declared in rak-plugin.json and enforced across all four surfaces:
| Surface | CleverCase touchpoint |
|---|---|
| worker | Docker worker boot, sealed env |
| gateway | Inference response sanitization |
| mcp | Tenant-scoped tool allowlist |
| sdk | PAT-scoped telemetry |
Verify: clevercase shield status / clevercase shield audit
RSP pipeline (tenant-scoped)
CleverCase feature delivery flows through the Rakontevr Story-First Pipeline:
| Step | Tool / command |
|---|---|
| Backlog | MCP rsp_stories |
| Create story | MCP rsp_story_create |
| Execute (tenant) | MCP rsp_execute_tenant — not platform rsp_execute |
| Phase gate | MCP rsp_check |
| Verify | MCP rsp_audit + phase evidence |
Packages in this repo
| Package | Description |
|---|---|
packages/rak-plugin-clevercase | Domain plugin — schema, migrations, Shield, MSO RBAC |
packages/cursor-plugin-clevercase | Cursor rules, skills, slash commands (/cc-rsp, /cc-verify) |
vendor/rakontevr/sdk | Vendored telemetry SDK |
vendor/rakontevr/appkit-* | BuilderHub UI kit vendored copies |
Build plugin: npm run build:rak-plugin
Troubleshooting
| Symptom | Fix |
|---|---|
| MCP tools missing | Re-run clevercase setup; check RAK_TENANT_ID |
| 403 on inference | Service key missing inference scope — re-run provision-full |
| Gladys 503 | Set RAKONTEVR_SERVICE_KEY in .env.local |
| Gateway unreachable | Use hosted URL + Tailscale, or rak gateway status |
| Cross-repo imports | Remove — use HTTP integration only |
Related pages
- System Design — container diagram
- Data Flow — Gladys SSE sequence
- Architecture Book — Rakontevr Platform — narrative deep-dive