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

# API Keys and Fable 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

After creation you can download:
- **`.env` file** — `FABLE_URL` + `FABLE_API_KEY` ready to paste
- **Claude config JSON** — `mcpServers` block ready to merge into `~/.claude.json`

### Revoking a Key

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

---

## Fable MCP Server

The Fable MCP server (`fable-mcp`) exposes Fable as a set of MCP tools that Claude (and other MCP clients) can use to read and write your notes, tasks, projects, and more.

### Download

The wheel is bundled into the Docker image at build time and available for download from **Settings → API Keys → Fable MCP** when you are logged in.

You can also download it directly:
```
GET /api/fable-mcp/download
```
(Requires login — authenticated browser session or API key in `Authorization: Bearer <key>` header.)

### Installation

```bash
# Install the wheel
pip install fable_mcp-*.whl

# Verify
fable-mcp --help
```

### Configuration

The server reads two environment variables:

| Variable | Description |
|----------|-------------|
| `FABLE_URL` | Base URL of your Fable instance (e.g. `https://notes.example.com`) |
| `FABLE_API_KEY` | API key generated from Settings → API Keys |

Create a `.env` file in your working directory, or set them in your shell / MCP config.

### Claude Code (Global)

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "fable": {
      "type": "stdio",
      "command": "fable-mcp",
      "env": {
        "FABLE_URL": "https://your-fable-instance.example.com",
        "FABLE_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Claude Code (Project-scoped)

Add a `.mcp.json` at the project root (same format as the global config). Project-scoped config takes precedence over global when the same server name is defined in both. This is useful for using a dev instance or admin key within a specific project.

```json
{
  "mcpServers": {
    "fable": {
      "type": "stdio",
      "command": "fable-mcp",
      "env": {
        "FABLE_URL": "http://localhost:5000",
        "FABLE_API_KEY": "your-dev-api-key"
      }
    }
  }
}
```

Note: `.mcp.json` contains an API key and should be added to `.gitignore`.

### Available Tools

| Tool | Description |
|------|-------------|
| `fable_list_notes` | List notes, filter by tag or search text |
| `fable_get_note` | Fetch a note by ID |
| `fable_create_note` | Create a new note |
| `fable_update_note` | Update a note |
| `fable_delete_note` | Delete a note |
| `fable_list_tasks` | List tasks, filter by status or project |
| `fable_get_task` | Fetch a task by ID |
| `fable_create_task` | Create a new task |
| `fable_update_task` | Update a task |
| `fable_add_task_log` | Append a work log entry to a task |
| `fable_list_projects` | List all projects |
| `fable_get_project` | Fetch a project with milestone summary |
| `fable_create_project` | Create a project |
| `fable_update_project` | Update a project |
| `fable_list_milestones` | List milestones for a project |
| `fable_create_milestone` | Create a milestone |
| `fable_update_milestone` | Update a milestone |
| `fable_search` | Semantic search over notes and tasks |
| `fable_list_conversations` | List MCP chat conversations |
| `fable_send_message` | Send a message to Fable's LLM |
| `fable_get_app_logs` | Fetch application logs (admin key required) |

### Development Notes

The `fable-mcp` package lives in `fable-mcp/` in this repository. The Docker build compiles it into a wheel at `/app/dist/` so it can be served for download without requiring the source tree at runtime.

To build the wheel locally:
```bash
cd fable-mcp
pip install build hatchling
python -m build --wheel .
```