bvandeusenandClaude Opus 5
0bcd4b5540
A rule's home is its scope now: a rule in a rulebook topic is global, a rule on a project applies to that project, and retrieval reads that directly (#4074). A subscription had stopped changing anything a session received; a suppression muted rules from a subscription. Operator, 2026-09-15: "we have global and project scoped rules, we don't need the subscriptions now." What goes, whole (rule 22): - Migration 0101 drops project_rulebook_subscriptions, project_rule_suppressions and project_topic_suppressions, and strips subscribe_rulebooks (and 394's leftover exclude_always_on_rulebooks) from stored inception choices. - Service, MCP and REST: subscribe/unsubscribe and the four suppress/unsuppress operations. The Subscribers checklist, the subscribe chips, the skip buttons and the Suppressed section in the rules UI. - Inception asks two questions (design system, seed Systems). create_project and decide_project_inception lose subscribe_rulebooks. - Backup v15 stops exporting the three sections; older archives still restore, the keys simply unread. Trash no longer hard-deletes suppression rows. What changes meaning: - get_applicable_rules is a project's LISTING: its own rules, plus the global rules tagged to an area it works in. Untagged global rules apply everywhere and arrive by retrieval, so they are not listed. A co_surfaces partner on a different project is not dragged in. - list_rules(project_id) lists that project's own rules. - rules_payload drops subscribed_rulebooks and suppressed_*; the handshake's brief form is project_rules alone. - using-scribe's "Where a new rule goes" and inception sections, tool docstrings and docs say global vs project. Plugin 2026.09.15.1620. Milestone 414 step 2. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy
4.1 KiB
API Keys and Scribe MCP
API Keys
API keys let external tools access your Fable data without a browser session. Each key is scoped to a single user — it can only access data that user owns or has been shared with them.
Scopes
| Scope | Permissions |
|---|---|
read |
GET endpoints only — list, search, fetch content |
write |
Full read + create, update, delete |
Admin-level operations (log access, user management) require a write-scoped key from an admin account.
Creating a Key
- Go to Settings → API Keys
- Enter a name (e.g. "Claude MCP", "Home Server")
- Choose scope
- Click Generate Key
- Copy the key immediately — it is shown only once (the token is
fmcp_-prefixed)
Paste the key into the Authorization: Bearer <key> header of your MCP client
config (see Scribe MCP Server below).
Revoking a Key
Click Revoke next to the key in the API Keys table and confirm. Revoked keys are deleted immediately.
Scribe MCP Server
Scribe exposes itself as a set of MCP tools that Claude (and other MCP clients)
can use to read and write your notes, tasks, projects, rulebooks, and more. The
server is built into the app — it is mounted as a streamable-HTTP endpoint
at /mcp on the running Scribe instance (src/scribe/mcp/server.py). There
is nothing to install: no wheel, no separate package, no CLI. You connect a
client straight to the URL with a Bearer token.
Authentication
Authenticate with an API key generated from Settings → API Keys (see above),
sent as Authorization: Bearer fmcp_<key>. A read-scoped key may call only the
read tools (get_*, list_*, search, enter_project, retrieval_telemetry);
any write/delete tool is rejected with 403. The allow-list is explicit rather
than derived from the name — see _READ_ONLY_TOOLS, which is why the two reads
without a read-shaped name are spelled out here. A write-scoped key may call everything.
Claude Code (Project-scoped)
Add a .mcp.json at the project root. The server type is http and the URL is
your instance's /mcp endpoint:
{
"mcpServers": {
"scribe": {
"type": "http",
"url": "https://your-scribe-instance.example.com/mcp",
"headers": {
"Authorization": "Bearer fmcp_your-api-key"
}
}
}
}
Note: .mcp.json contains an API key and should be added to .gitignore.
Claude Code (Global)
The same mcpServers block can live in ~/.claude.json to make the server
available across all projects. A project-scoped .mcp.json takes precedence over
the global entry when both define the same server name — useful for pointing a
specific project at a dev instance or an admin key.
Available Tools
The tool surface is large (~70 tools) and evolves with the app, so the live
registration in src/scribe/mcp/tools/ is the source of truth rather than a
table here. The tools are grouped by family:
| Family | Examples | Purpose |
|---|---|---|
| Notes | create_note, get_note, update_note, delete_note, list_notes |
Free-form knowledge |
| Tasks | create_task, update_task, add_task_log, start_planning |
Actionable work + plans |
| Projects / Milestones | enter_project, get_project, create_milestone, … |
Containers and outcomes |
| Search / Recall | search, get_recent, list_tags, retrieval_telemetry |
Semantic + structured recall, and the readout its thresholds are tuned from |
| Systems | create_system, list_systems, list_system_records |
Reusable per-project subsystems/areas |
| Rulebooks | list_rules, create_rule, create_project_rule, relate_rules, … |
Engineering/workflow rules |
| Processes | list_processes, get_process, create_process |
Saved prompts/workflows |
| Trash | list_trash, restore, purge_trash |
Recoverable deletes |
| Admin | get_app_logs (write/admin key) |
Diagnostics |
Server-level usage guidance — when to reach for each entity, the
recall-before-acting reflex, and the rulebook conventions — is delivered to the
client automatically via the MCP server's instructions block (defined in
src/scribe/mcp/server.py).