User Guide

Welcome to the user guide for Jupyter AI. Make sure to see our guide on Getting Started if you haven’t already, which covers installation and setup.

Using the chat interface

Create a new chat

Once you have started JupyterLab, click the new “chat” icon in the left side panel to open the chat interface. You can right-click on the panel icon and move it to the other side, if you prefer.

After clicking New Chat, you will see a new chat created in your side panel:

This will open a prompt to name the chat. Give it a reasonable name:

You can create new chats as you go and these will persist after you close JupyterLab. When re-opening JupyterLab you can see existing chats in the chat panel as shown here:

Use an AI persona

An AI Persona is an agent or harness that responds to prompts in the chat panel. You can address more than one persona in any chat session. AI personas always respond to user messages in the chat panel when selected.

You can use the persona picker in the chat as shown below.

A persona can allow access to different models and each one comes with a model picker as well, allowing you to select which model to use for that persona, and also switch models for the same persona in the same chat session. The model picker is shown below:

To compose a message, type it in the text box at the bottom of the chat interface and press ENTER to send it. You can press SHIFT+ENTER to add a new line. Once you have sent a message, you should see a response from the AI persona.

You can also see the Delete button shown alongside the prompt if you need to clear up the chat; there is a similar button in the response area as well.

As another example, see how Claude can be used via ACP in the following screens, with the various selection options for models, attributes, mode, and token counts, cost, etc.

Model picker

Model Mode

Selecting Effort

Token counts, cost

Chat features

Chats are files

Chats are appear as files named <chat_name>.chat. Each .chat file contains the entire history of the chat. These files are saved to disk, so you can resume any chat by re-opening the .chat file.

You can also delete a chat simply by deleting the corresponding .chat file.

Chats are threads

You can create multiple chats to manage different threads of conversation. From the chat side panel, you can click + New chat to open a new chat to start a different thread.

Add attachments

The chat panel supports message attachments, which allow you to share additional context with an AI persona without copying and pasting.

The easiest way to do this is to simply drag and drop a file into the chat input. This will add the file as an attachment. You may also drag and drop notebook cells into the chat input. You may also use the file picker UI by clicking the paperclip icon in the chatbox.

AI personas will read message attachments and use them to assist with your request.

The @file command

Another way of adding attachments is offered through the @file:<file-path> command, which allows you to quickly attach a file given its path. This will open an auto-complete menu that helps navigate your workspace’s file tree to find the right file to add.

Personas reply intelligently

Personas reply intelligently based on the number of other connected users and other AI personas. If you are the only user connected to your JupyterLab server, the current active persona will always reply.

Code toolbar shortcuts

Jupyter AI provides some quick shortcuts for code blocks returned by an agent. You can use these to copy the code to your clipboard, insert it as a notebook cell above/below the active cell, or replace the active cell of a notebook in the main area.

How Jupyter AI interacts with agents

Jupyter AI is the chat host inside JupyterLab. It provides the chat interface, keeps track of the conversation, and routes each message to an AI persona. A persona is the integration point for an agent or model; it is not the model itself. This distinction is useful when deciding where a setting or a tool belongs.

Component	Role in a Jupyter AI session
Chat panel	Collects messages, attachments, and tool permission decisions, then displays streamed replies.
AI persona	Receives a message and produces a reply. The persona may call a model directly or hand the message to an external agent.
ACP integration	Connects Jupyter AI to an external agent through the Agent Client Protocol. The agent reports its available models, modes, and permissions back to the chat.
Jupyter MCP server	Exposes notebook and JupyterLab operations as MCP tools, so an agent can inspect or change the workspace with the user’s permission.
Custom MCP server	Adds another tool source through the workspace’s .jupyter/mcp_settings.json configuration.

The usual message flow is:

1. You send a message in a chat and optionally select a persona or attach a notebook cell or file.

2. Jupyter AI routes the message to the selected persona. If the persona wraps an ACP agent, the persona forwards the request to that agent and streams the agent’s events back to the chat.

3. The agent or persona decides whether it needs a model, a notebook tool, or a custom MCP tool. Tool calls can require approval before they run.

4. The result is streamed back through the persona to the chat panel. Any files, notebook edits, or other workspace changes are made by the tool that was called, not by the chat panel itself.

This means Jupyter AI can participate in several protocol roles in one session:

• Jupyter AI acts as an ACP client when it connects an external ACP agent to the chat.

• The Jupyter server acts as an MCP server when it exposes notebook tools to an agent.

• An external MCP server can be configured as another tool source. In that arrangement, the agent is the MCP client and Jupyter AI supplies the configuration.

For some direct model-backed personas, there is no ACP hop: the persona calls its configured model provider itself. For example, Jupyternaut can use the provider and model selected in its settings while still using the same Jupyter MCP tools. For a custom persona, the main application hook is process_message(). See the developer guide for the persona API and entry-point setup.

Notebook tools

By default, AI personas have access to the MCP server provided by the jupyter_server_mcp package. Jupyter AI uses this to provide a notebook toolkit to all AI personas by default.

These tools allow AI personas to:

• Answer questions about your active notebook or active cell

• Create and edit notebooks

• Run code cells through the kernel

• Open other files in JupyterLab

Custom MCP servers

You can share custom MCP servers to extend the capabilities of your AI personas and tailor them to your workflow.

To add custom MCP servers, create a .jupyter/mcp_settings.json file at the root of your workspace. This file contains an array of MCP server configurations under mcp_servers. Jupyter AI reads this file on startup and makes the configured servers available to all ACP agents automatically.

Stdio servers

A stdio server runs as a local process. You specify the command and arguments to launch it:

{
  "mcp_servers": [
    {
      "name": "My Custom Tools",
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": [
        {"name": "API_KEY", "value": "sk-abc123"}
      ]
    }
  ]
}

Field	Type	Required	Description
name	string	yes	Human-readable name identifying this MCP server.
command	string	yes	Path to the MCP server executable.
args	list of strings	yes	Command-line arguments to pass to the server.
env	list of objects	no	Environment variables to set when launching. Each object has name and value fields.

HTTP servers

An HTTP server is a remote MCP server accessible over HTTP:

{
  "mcp_servers": [
    {
      "type": "http",
      "name": "Remote Tools",
      "url": "https://my-mcp-server.example.com/mcp",
      "headers": [
        {"name": "Authorization", "value": "Bearer my-token"}
      ]
    }
  ]
}

Field	Type	Required	Description
type	"http"	yes	Must be "http" for HTTP servers.
name	string	yes	Human-readable name identifying this MCP server.
url	string	yes	URL to the MCP server.
headers	list of objects	no	HTTP headers to include in requests. Each object has name and value fields.

Full example

Here is a complete .jupyter/mcp_settings.json with both server types:

{
  "mcp_servers": [
    {
      "name": "Filesystem Tools",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    {
      "name": "GitHub Tools",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": [
        {"name": "GITHUB_PERSONAL_ACCESS_TOKEN", "value": "ghp_xxx"}
      ]
    },
    {
      "type": "http",
      "name": "Company Internal Tools",
      "url": "https://internal-mcp.corp.example.com/mcp",
      "headers": [
        {"name": "Authorization", "value": "Bearer my-token"}
      ]
    }
  ]
}

After saving this file, restart JupyterLab for the changes to take effect. All configured MCP servers will be available to every ACP agent in your session.