FabledScribe/docs/api-keys-and-mcp.md

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

1. Go to Settings → API Keys
2. Enter a name (e.g. "Claude MCP", "Home Server")
3. Choose scope
4. Click Generate Key
5. 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); any write/delete tool is rejected with 403. 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	Semantic + structured recall
Typed entities	create_person, create_place, create_list, …	Structured records
Events	create_event, list_events, update_event, …	Calendar
Rulebooks	list_always_on_rules, list_rules, create_rule, create_project_rule, subscribe_project_to_rulebook, …	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).