Jupyter Collaboration

You can expose Jupyter Collaboration’s real-time RTC features to AI agents through an MCP server. This enables agents to collaborate on notebooks and documents, see user presence and cursors, and participate in a streamed, authenticated session with resumable connections.

How to use

Connect an MCP client to the Jupyter Collaboration MCP Server to access real-time notebook and document collaboration, user awareness, and session management. Use the HTTP MCP endpoint to initialize collaboration sessions, fetch content, and stream updates. Authenticate each request with the provided token to ensure secure access.

How to install

Prerequisites you must have before installing this MCP server are Python 3.10 or higher and Jupyter Server 2.0.0 or higher.

Install the MCP server package with the following commands. Run each line separately to install the MCP server as a Jupyter server extension.

Configuration and security

The MCP server is configured to be loaded automatically when the MCP package is installed as a Jupyter server extension. For security, authentication uses a simple token-based mechanism. Start Jupyter Lab with a token, and include this token in your MCP client requests.

{
  "mcpServers": {
    "jupyter_collaboration": {
      "url": "http://localhost:8888/mcp",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Identity.token your-secret-token"
      },
      "disabled": false
    }
  }
}

Troubleshooting

If you encounter authentication errors, verify you are using the correct token in your Authorization header. If the MCP endpoint cannot be reached, ensure the Jupyter server is running and the MCP extension is loaded. For browser-based clients, check that the server permits the origin of your client requests (CORS) or adjust the server configuration accordingly.

Notes

This MCP server exposes a set of tools for interacting with notebooks, documents, and user awareness. Use the provided HTTP endpoint to establish sessions and exchange real-time updates between AI agents and your Jupyter Collaboration environment.

Available tools

list_notebooks

List available notebooks in the collaboration environment.

get_notebook

Retrieve the content of a specific notebook.

create_notebook_session

Create or retrieve a collaboration session for a notebook.

update_notebook_cell

Update the content of a notebook cell.

insert_notebook_cell

Insert a new cell into a notebook.

delete_notebook_cell

Delete a cell from a notebook.

execute_notebook_cell

Execute a specific notebook cell.

list_documents

List available documents in the collaboration space.

get_document

Get the content of a document.

create_document_session

Create or retrieve a collaboration session for a document.

update_document

Update document content.

insert_text

Insert text at a specified position in a document.

delete_text

Delete text from a specified position in a document.

get_document_history

Retrieve the version history of a document.

restore_document_version

Restore a document to a previous version.

fork_document

Create a fork of a document.

merge_document_fork

Merge a document fork back into the original.

get_online_users

List users currently online in the collaboration session.

get_user_presence

Get presence information for a user.

set_user_presence

Set the current user's presence status.

get_user_cursors

Get cursor positions of users in a document.

update_cursor_position

Update the current user's cursor position.

get_user_activity

Fetch recent user activities.

broadcast_user_activity

Broadcast user activity to other participants.

get_active_sessions

List active collaboration sessions.

join_session

Join a collaboration session.

leave_session

Leave a collaboration session.