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

API Keys and Grimoire MCP

API Keys

API keys let external tools access your Grimoire 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 → MCP Access
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 Grimoire MCP Server below).

Revoking a Key

Click Revoke next to the key in the keys table and confirm. Revoked keys are deleted immediately.

---

Grimoire MCP Server

Grimoire 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 Grimoire instance (src/grimoire/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 → MCP Access (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: the plugin (recommended)

The plugin connects the MCP server and adds the hooks and skills that put Grimoire's records in front of Claude as it works. Install it from this repo:

/plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledGrimoire.git
/plugin install grimoire@grimoire-plugin

It asks for your Grimoire base URL, an API key (kept in your OS keychain) and, optionally, a project id. Settings → MCP Access shows the exact command for your instance. plugin/README.md describes each hook.

Claude Code without the plugin

Add a .mcp.json at the project root. The server type is http and the URL is your instance's /mcp endpoint:

{
  "mcpServers": {
    "grimoire": {
      "type": "http",
      "url": "https://your-grimoire-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

There are well over a hundred tools and they change with the app, so the registration in src/grimoire/mcp/tools/ is the reference. By family:

Family	Examples	Purpose
Notes	create_note, get_note, update_note, create_records	Knowledge, and several records that cite each other in one call
Tasks	create_task, update_task, add_task_log	Work, issues and spikes, and their logs
Projects / Milestones	enter_project, start_planning, get_milestone	Projects and their plans
Search / Recall	search, what_might_apply, get_recent	Recall by meaning, and the rules that may apply to an act
Systems	create_system, list_system_records, map_system_to_canonical	A project's areas
Rules	create_rule, create_project_rule, relate_rules, rule_history, list_moments	Rules, preferences, their relations and moments
Lessons	create_lesson, judge_lesson_link	Lessons and the rules they instance
Snippets / Shapes	create_snippet, verify_snippet, classify_shapes, list_shapes	Prior art and the shape ledger
Design systems	resolve_design_system, get_design_system_stylesheet	Tokens and guidance for UI work
Family canon	list_family_ideas, assess_family_adoption	Ideas shared across projects
Processes	list_processes, get_process, create_process	Stored procedures
Retrieval	retrieval_telemetry, tune_retrieval	What was surfaced, and the thresholds
Trash	list_trash, restore, purge_trash	Recoverable deletes

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/grimoire/mcp/server.py).