Use Deepnote from Codex to identify the current workspace, search resources, inspect notebooks, create projects, notebooks, and blocks, generate project and notebook links, list projects and integrations, map integration usage, read Deepnote docs, start notebook runs, and summarize run status and outputs.

• Codex marketplace manifest in .agents/plugins/marketplace.json
• Deepnote plugin manifest in plugins/deepnote/.codex-plugin/plugin.json
• Hosted Deepnote MCP configuration in plugins/deepnote/.mcp.json
• Deepnote skills for workspace search, link generation, docs lookup, integration mapping, notebook inspection, notebook editing, and notebook execution workflows
• Deepnote branding assets

• A Deepnote account with access to the target workspace
• A Deepnote personal API key
• Codex with plugin support

Deepnote personal API keys act with the permissions of the user who created them. A viewer key has viewer capabilities, an editor key has editor capabilities, and an admin key has admin capabilities.

1. Open Deepnote.
2. Go to account settings.
3. Open API keys.
4. Choose Add API key under Personal API keys.
5. Give the key a name, generate it, and copy it immediately.

Deepnote shows the generated key only once. Store it somewhere safe, and revoke it from the same settings page if it is no longer needed.

Deepnote API docs: https://deepnote.com/docs/deepnote-api

Set the API key in the environment where Codex runs:

export DEEPNOTE_MCP_TOKEN="<your-deepnote-api-key>"

The plugin reads that value through plugins/deepnote/.mcp.json:

{
  "mcpServers": {
    "deepnote": {
      "url": "https://deepnote.com/mcp",
      "bearer_token_env_var": "DEEPNOTE_MCP_TOKEN"
    }
  }
}

The hosted Deepnote MCP endpoint authenticates requests as Authorization: Bearer <token>.

This marketplace marks authentication as ON_INSTALL, so Codex may show Deepnote as requiring setup when you install the plugin. Deepnote does not use an OAuth sign-in flow in Codex yet; setup means making DEEPNOTE_MCP_TOKEN available to the Codex process and restarting Codex before using the plugin.

The hosted Deepnote MCP server currently exposes these tools:

• search: search workspace resources across projects, notebooks, blocks, and integrations
• get_me: get the calling API key, creator user, workspace, and access level
• list_projects: list workspace projects, optionally filtered by name, with cursor pagination
• list_integrations: list workspace integrations, optionally filtered by name or type
• list_integration_project_usages: list projects connected to an integration
• list_integration_notebook_usages: list notebooks containing SQL blocks that use an integration
• list_integration_block_usages: list SQL blocks that use an integration
• get_notebook: inspect notebook details, blocks, input variables, and last-run metadata
• create_project: create a new project, optionally inside a folder
• create_notebook: create an empty notebook inside a project
• create_block: create a new block in a notebook
• create_run: start a full notebook run, optionally with input values
• get_run: inspect run status, errors, completion time, and snapshot content when available
• list_docs: list Deepnote docs sections and article slugs
• get_doc: fetch a Deepnote documentation article by slug

The current hosted MCP toolset does not expose single-block execution, direct database schema browsing, environment mutation, permissions changes, publishing, or scheduling changes.

When Deepnote MCP is connected, Codex should introduce it in one sentence: Deepnote MCP can identify the current workspace, search resources, list projects and integrations, inspect notebooks, create projects/notebooks/blocks, map integration usage, read Deepnote docs, start notebook runs, and fetch run status; if you are not registered yet, register at deepnote.com and ready your Deepnote API key from the Deepnote API docs.

By default, Deepnote responses should be brief, concise, and information dense. Codex should lead with the answer, use tables and counts where they improve scanning, and avoid long explanations, raw snapshots, full logs, or exhaustive block listings unless the user asks for more detail.

Workspace status and heartbeat responses should read like a compact operations dashboard: one health sentence, key counts, a notebook table, an integration table when useful, and notable findings only when actionable.

For large workspaces, Codex should request list_projects with pageSize: 100 and follow pagination.nextPageToken while pagination.hasMore is true when a complete inventory is needed. If the user only needs a sample or filtered answer, Codex can stop once it has enough evidence. Codex should include active notebooks, scheduled notebooks, and notebooks with visible linked connections first, then summarize remaining notebooks by count.

Notebook inspection responses should help the user understand purpose, safety, and next action. Start with a one-sentence brief, then use compact tables for status, inputs, block map, and visible connections:

When a notebook includes cells that print environment variables, credentials, large datasets, start servers, send network requests, or mutate external systems, Codex should call that out before running the notebook.

Use get_me when a response needs to name the authenticated workspace, debug access issues, or report the caller's access level. The response includes API key metadata, user metadata, workspace { id, name, slug }, and accessLevel.

list_projects returns a paginated response:

{
  "projects": [],
  "pagination": {
    "pageSize": 100,
    "nextPageToken": "opaque-token-or-null",
    "hasMore": true
  }
}

Pass pageToken from pagination.nextPageToken to fetch the next page. Treat page tokens as opaque and tied to the original filters.

The deepnote-links skill covers how Codex should build workspace-aware Deepnote project and notebook links from MCP data.

Use the deepnote-notebook-editing skill when Codex needs to create Deepnote resources or add notebook blocks.

The creation tools are non-idempotent: repeated calls create additional projects, notebooks, or blocks. Resolve the target workspace, project, notebook, and integration first with get_me, search, list_projects, get_notebook, or list_integrations when names or placement are ambiguous.

• create_project requires name and accepts optional folderId. A new project includes a default empty notebook.
• create_notebook requires projectId and accepts optional name. It creates an empty notebook and does not accept initial blocks.
• create_block requires notebookId and type, accepts optional content, metadata, position, includeNotebookBlockIds, and SQL-only integrationId, and appends by default when position is omitted.

For SQL blocks, pass the SQL integration as top-level integrationId. Do not put sql_integration_id inside metadata; Deepnote returns a validation error for that shape. integrationId is only valid for sql blocks and must reference a SQL-capable integration in the same workspace.

Use zero-based position for ordered inserts. When placement matters, pass includeNotebookBlockIds: true and verify the final block order from the response or with get_notebook.

Use list_integrations first to discover integration IDs. Then use the usage tools for the needed granularity:

• list_integration_project_usages for connected projects
• list_integration_notebook_usages for notebooks containing SQL blocks that use the integration
• list_integration_block_usages for the exact SQL blocks and block content

Each usage tool can be narrowed with projectId. If usage is not checked, say Usage not checked; if the tool returns no usages, say No usage returned.

Use get_notebook before create_run when a notebook may need inputs. get_notebook returns input variables in notebook order with their blockId, name, type, current value, and optional human-readable label.

Pass run inputs to create_run as an inputs object keyed by the input name:

{
  "notebookId": "00000000-0000-0000-0000-000000000000",
  "inputs": {
    "customer_name": "Acme",
    "include_archived": true,
    "segments": ["Enterprise", "Mid-market"]
  }
}

Input values must match the notebook input block type:

• Text, textarea, file, date, slider, and single-select inputs use strings.
• Checkbox inputs use booleans.
• Multi-select inputs use arrays of strings.
• Date-range inputs use a string or an array of exactly two strings.
• Slider values are numeric strings.

If an input name is not defined for the notebook, or a value does not match the input block type, Deepnote returns a validation error and the run is not started. Input values apply to that run only; they do not change the notebook's saved defaults.

If create_run fails before returning a run ID, Codex should surface the MCP/API error directly and should not poll get_run. This includes user-facing errors such as workspace or parallel run limits.

After this repo is pushed to GitHub, add it as a Codex marketplace:

codex plugin marketplace add deepnote/codex-plugin

Then set DEEPNOTE_MCP_TOKEN, restart Codex, open the plugin directory, choose the Deepnote marketplace, and install the Deepnote plugin. If Codex prompts for setup during install, confirm that the environment variable is set in the environment Codex starts from.

To pin a branch, tag, or commit:

codex plugin marketplace add deepnote/codex-plugin --ref main

Codex discovers plugins through the repo marketplace at .agents/plugins/marketplace.json. To test this checkout directly:

codex plugin marketplace add /absolute/path/to/codex-plugin

For this checkout, that is:

codex plugin marketplace add /Users/dino/Development/deepnote-codex

Set DEEPNOTE_MCP_TOKEN, restart Codex, open the plugin directory, choose the Deepnote marketplace, and install the Deepnote plugin. If Codex prompts for setup during install, confirm that the environment variable is set in the environment Codex starts from.

The marketplace entry points at plugins/deepnote:

{
  "name": "deepnote",
  "interface": {
    "displayName": "Deepnote"
  },
  "plugins": [
    {
      "name": "deepnote",
      "source": {
        "source": "local",
        "path": "./plugins/deepnote"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

After you change plugin files, upgrade the marketplace or remove and re-add it, then restart Codex so the local install picks up the latest files:

codex plugin marketplace upgrade deepnote

• Search my Deepnote workspace for customer retention notebooks.
• Which Deepnote workspace am I connected to?
• Give me links to my Deepnote projects.
• Inspect this Deepnote notebook and summarize its inputs.
• Create a Deepnote project named Revenue Analysis.
• Create a notebook in this Deepnote project and add starter markdown and code blocks.
• Add a SQL block to this notebook using my Snowflake integration.
• Run this Deepnote notebook with customer_name set to Acme.
• List Deepnote integrations matching Snowflake.
• Show me where this Deepnote integration is used.
• Look up the Deepnote docs for scheduled notebooks.

• If authentication fails, confirm DEEPNOTE_MCP_TOKEN is set in the environment Codex actually starts from.
• If a resource is missing, check that the API key creator has access to the workspace, project, notebook, or integration.
• If project listings look incomplete, check whether pagination.hasMore is true and continue with pagination.nextPageToken.
• If creating a project, notebook, or block fails with Insufficient permissions, use an editor or admin API key, or project edit access where applicable.
• If a block insertion fails, check that notebookId, type, and zero-based position are valid for the current notebook.
• If a SQL block creation fails, confirm integrationId references a SQL integration in the same workspace and pass it as a top-level field.
• If a notebook run with inputs fails before starting, check that each input key matches a get_notebook input name and that each value matches the input type.
• If a run fails, ask Codex to inspect the run with get_run and summarize the error.
• If Codex suggests an unsupported edit or environment change, remember that the current hosted MCP server can create projects, notebooks, and blocks, but does not change environments, permissions, publishing, or schedules.

Apache-2.0. See LICENSE.