OpenNotebook MCP Multitenant Proxy Server

This repository contains a Model Context Protocol (MCP) server that acts as a secure, multi-tenant proxy between an AI Assistant and the OpenNotebook backend API. It exposes 81 MCP tools covering 14 resource domains with full CRUD, search, chat, podcast, and command management.

✨ Features

• 🔑 Identity Passthrough — Extracts the Authorization: Bearer <token> header from incoming HTTP requests and forwards it to the OpenNotebook API without server-side authentication.
• 👥 Multi-Tenancy — Uses Python contextvars to maintain thread-safe user identity isolation, ensuring all AI-driven actions are scoped to the authenticated user's permissions.
• 📊 Full OpenNotebook Coverage — 81 tools mapped to OpenNotebook API endpoints across 14 resource domains.
• ⚡ TOON Optimization — Bulk list responses are automatically compressed using TOON (Token-Optimized Object Notation) to reduce token consumption and maximize context window efficiency.
• 🚀 Efficient Gets — GET responses return only commonly used fields by default. Full objects are available via an include_all_fields flag.
• 🧪 Comprehensive Testing — 109 automated tests covering all tool domains, run via the test runner pipeline.
• 🏷️ Tool Annotations — All tools expose standard MCP ToolAnnotations hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). The tags field carries grouping metadata (basic/primary/advanced + opennotebook).

🔧 Environment Variables

Variable	Required	Description
OPENNOTEBOOK_BASE_URL	Yes	Docker-internal URL of the OpenNotebook API
MCP_SERVER_PORT	Yes	Port number the MCP server listens on
ALLOW_ALL_AGGREGATE	No	When true, aggregate listing tools honor the include_all_fields parameter. When false (default), the parameter is silently forced to False for aggregate list operations.
IS_STATEFUL	No	When true, uses stateful Streamable HTTP with session tracking. When false (default), uses stateless mode.

📦 Installation & Local Development

1. Ensure you have Python 3.12+ installed.
2. Install dependencies:

   pip install fastmcp httpx pydantic uvicorn toon-mcp-server
   

3. Run the server:

   export OPENNOTEBOOK_BASE_URL=http://localhost:5055
   export MCP_SERVER_PORT=80
   python -m src.main
   

🐳 Docker Deployment

Build and run the server using Docker:

docker build -t opennotebook-mcp:latest .
docker run -d --name opennotebook-mcp \
    -e OPENNOTEBOOK_BASE_URL="http://opennotebook-app:5055" \
    -e MCP_SERVER_PORT=80 \
    opennotebook-mcp:latest

The MCP server serves at http://opennotebook-mcp:80/mcp (Streamable HTTP).

⚠️ Important Notes

• 📋 include_all_fields — The include_all_fields parameter (available on all get_* and list_* tools) controls whether all available fields are included in responses. Defaults to False for performance; set to True only when additional fields are needed.
• ⚡ TOON Compression — All bulk list responses are automatically compressed using TOON to reduce token consumption by 30–60%.
• 📝 Required Fields & Defaults — Each create_* tool requires specific key fields. All other fields default to empty strings or reasonable values. The owner field is automatically set to the authenticated user for most resources.

🛠️ API Tool Mapping

The server implements 81 MCP tools organized into the following categories:

📓 Notebooks (9 tools)

• check_server_status — Check the health and status of the OpenNotebook backend API
• list_all_notebooks — List all notebook records
• get_notebook_by_id — Get a single notebook by ID
• create_notebook — Create a new notebook
• update_notebook — Update an existing notebook
• delete_notebook_by_id — Delete a notebook by ID
• get_notebook_delete_preview — Get a preview of what will be deleted
• add_source_to_notebook — Add an existing source to a notebook
• remove_source_from_notebook — Remove a source from a notebook
• list_recently_viewed — List recently viewed items

📝 Notes (5 tools)

• list_all_notes — List all note records
• get_note_by_id — Get a single note by ID
• create_note — Create a new note
• update_note — Update an existing note
• delete_note_by_id — Delete a note by ID

🔗 Sources (8 tools)

• list_all_sources — List all source records
• get_source_by_id — Get a single source by ID
• create_source — Create a new source (link or text type)
• update_source — Update an existing source
• delete_source_by_id — Delete a source by ID
• get_source_status — Get processing status for a source
• retry_source_processing — Retry processing for a failed source
• list_source_insights — List all insights for a source
• create_source_insight — Start insight generation for a source

💡 Insights (4 tools)

• get_insight_by_id — Get a single insight by ID
• delete_insight_by_id — Delete an insight by ID
• save_insight_as_note — Convert an insight to a note
• list_source_insights — List insights for a source

🔍 Search & Settings (4 tools)

• search_knowledge_base — Search the knowledge base
• ask_knowledge_base_simple — Ask the knowledge base a question
• get_settings — Get all application settings
• update_settings — Update application settings

🤖 Models (5 tools)

• list_all_models — List all configured models
• create_model — Create a new model configuration
• delete_model_by_id — Delete a model by ID
• get_default_models — Get default model assignments
• update_default_models — Update default model assignments

🔄 Transformations (8 tools)

• list_all_transformations — List all transformation records
• get_transformation_by_id — Get a single transformation by ID
• create_transformation — Create a new transformation
• update_transformation — Update an existing transformation
• delete_transformation_by_id — Delete a transformation by ID
• execute_transformation — Execute a transformation on input text
• get_default_transformation_prompt — Get the default prompt
• update_default_transformation_prompt — Update the default prompt

🧩 Embedding (3 tools)

• embed_content — Embed content for vector search
• start_embedding_rebuild — Start a background rebuild job
• get_rebuild_status — Get rebuild operation status

💬 Chat (7 tools)

• list_chat_sessions — List chat sessions for a notebook
• create_chat_session — Create a new chat session
• get_chat_session — Get a chat session with messages
• update_chat_session — Update a chat session
• delete_chat_session — Delete a chat session
• execute_chat — Execute a chat request
• build_chat_context — Build notebook context

🔌 Source Chat (5 tools)

• create_source_chat_session — Create a source chat session
• list_source_chat_sessions — List source chat sessions
• get_source_chat_session — Get a source chat session
• update_source_chat_session — Update a source chat session
• delete_source_chat_session — Delete a source chat session

🎙️ Podcasts (6 tools)

• generate_podcast — Generate a podcast episode
• get_podcast_job_status — Get podcast job status
• list_podcast_episodes — List all podcast episodes
• get_podcast_episode — Get a specific episode
• retry_podcast_episode — Retry a failed episode
• delete_podcast_episode — Delete a podcast episode

🎬 Episode Profiles (6 tools)

• list_episode_profiles — List all episode profiles
• get_episode_profile — Get a profile by name
• create_episode_profile — Create a new episode profile
• update_episode_profile — Update an episode profile
• delete_episode_profile — Delete an episode profile
• duplicate_episode_profile — Duplicate an episode profile

🗣️ Speaker Profiles (6 tools)

• list_speaker_profiles — List all speaker profiles
• get_speaker_profile — Get a profile by name
• create_speaker_profile — Create a new speaker profile
• update_speaker_profile — Update a speaker profile
• delete_speaker_profile — Delete a speaker profile
• duplicate_speaker_profile — Duplicate a speaker profile

📋 Commands (4 tools)

• submit_command_job — Submit a command for background processing
• get_command_job_status — Get command job status
• list_command_jobs — List command jobs
• cancel_command_job — Cancel a running command job