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`](../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:

```json
{
  "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`).