Recipe, MCP client + Shelvia

Principle

Shelvia is not an MCP runtime, the client is. Shelvia is the MCP server that serves reviewed project memory. The same scope + BOLA + review-before-save rules that apply to REST also apply over MCP.

Setup

• Create a Workspace API token in Settings > API with scopes: memory.read + memory.context (read-only) OR + memory.candidates (write).
• MCP endpoint URL: https://shelvia.net/api/mcp
• Discovery metadata: https://shelvia.net/.well-known/oauth-protected-resource and https://shelvia.net/.well-known/oauth-authorization-server
• Auth header: Authorization: Bearer shv_live_<hex>

Transport

Streamable HTTP per the MCP spec. POST /api/mcp with Accept: application/json for a single JSON-RPC response, or Accept: text/event-stream for an SSE envelope around the same JSON body. Mcp-Session-Id is echoed back if the client supplies one.

POST https://shelvia.net/api/mcp
Authorization: Bearer shv_live_<hex>
Content-Type: application/json
Accept: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Available tools

• shelvia_search_project_memory, hybrid search over approved memory
• shelvia_get_project_context, full snapshot for one project
• shelvia_get_decisions / _sources / _constraints / _prompts / _next_steps
• shelvia_generate_context_pack, ranked pack for the next session
• shelvia_create_handoff, structured handoff doc
• shelvia_create_memory_candidate, write, enters review queue (scope: memory.candidates)

Example, Claude Desktop config

Claude Desktop reads MCP servers from a JSON config. The shape below registers Shelvia as an HTTP MCP server.

{
  "mcpServers": {
    "shelvia": {
      "url": "https://shelvia.net/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer shv_live_<hex>"
      }
    }
  }
}

Propose memory candidates safely

Agents propose. Humans approve. MCP clients can call shelvia_create_memory_candidate when a session produces a claim worth keeping. The candidate enters the review queue with status pending. A workspace member approves before it becomes trusted memory.

POST /api/mcp
Authorization: Bearer shv_live_<hex>
Content-Type: application/json
Idempotency-Key: agent-mcp-client-<session-id>-decision-<hash>

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "shelvia_create_memory_candidate",
    "arguments": {
      "project_id": "proj_123",
      "type": "decision",
      "title": "Use Resend for transactional email",
      "content": "Final claim, not raw chain-of-thought. Cite source URLs.",
      "source_url": "https://example.com/sources/resend-eval"
    }
  }
}

• Identity: create a narrow-scope Workspace API token per MCP client install (label it, e.g., "Claude Desktop local assistant"). Reuse shv_live_<hex> with memory.candidates + memory.context.
• Idempotency: pass the Idempotency-Key header shaped agent-mcp-client-<session-id>-<candidate-hash>. MCP clients retry; idempotency keeps the review queue clean.
• Runtime tag: emit a shelvia_log_continuation after each session with suggested_tool: "mcp-client". The candidate body itself does not carry a runtime field.
• Never write to trusted memory directly. Shelvia has no MCP tool that promotes a candidate. Promotion is a human approval action in the Shelvia review surface.
• Never log raw chain-of-thought. Keep candidate content to final claims; the validator strips cookies, authorization headers, and session tokens with structured error codes.
• Agents must not approve their own memory. shelvia_create_memory_candidate cannot self-approve; there is no MCP tool that flips a candidate to approved.

Observability (optional)

MCP clients can call the shelvia_log_continuation tool after a session to record which reviewed context was used and what the next step should be. This is an optional audit / observability emit, it does NOT become trusted memory and does NOT bypass review-before-save. Scope required: continuations.log.

POST /api/mcp
Authorization: Bearer shv_live_<hex>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "shelvia_log_continuation",
    "arguments": {
      "project_id": "proj_123",
      "next_best_action": "Continue the v2 launch checklist",
      "why": "MCP client read the Shelvia context pack to summarize prior decisions.",
      "suggested_tool": "mcp-client",
      "priority": "normal"
    }
  }
}

Safety notes

• Workspace anchor is on the token, not the client. A client cannot retarget Shelvia to a different workspace.
• BOLA: project_id passed in any tool call is validated against the token's workspace before the tool runs.
• Pending candidates are excluded from search responses by default. The shelvia_create_memory_candidate tool always lands a candidate in the review queue with status pending.
• The shelvia_log_continuation tool is audit-only. It does not write to trusted memory tables.
• MCP clients that ask for the manifest get tool names + scopes only, no token leakage, no connector secrets, no embedding vectors.

Where to go next

• MCP reference, /docs/developers/mcp
• Authentication scopes, /docs/developers/auth
• Review-before-save concept, /docs/concepts/review-before-save