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

# 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:

{
  "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.

{
  "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:

cd fable-mcp
pip install build hatchling
python -m build --wheel .