Skill instructions
deepnote4.07 KB
View saved version →
---
name: deepnote
description: Use when a task mentions Deepnote, the connected Deepnote app, Deepnote OAuth connection, Deepnote docs, projects, workspaces, notebooks, blocks, integrations, or notebook runs.
---
# Deepnote Router
Use the connected Deepnote app tools as the source of truth for hosted Deepnote state. Prefer them over browser automation, screenshots, ad hoc HTTP calls, or local filesystem guesses for Deepnote projects, notebooks, blocks, integrations, docs, or runs.
If the Deepnote app tools are unavailable, say so and ask the user to connect the Deepnote app with OAuth. Do not pretend to have inspected Deepnote state.
When the user asks what Deepnote can do, start with:
Deepnote can identify the current workspace, search resources, list projects and integrations, inspect notebooks, create and edit notebook structure, map integration usage and cached table structure, read Deepnote docs, run notebooks, and fetch run status and history.
## Capability Map
Use the current tool surface only; if a required tool is absent, say which capability is missing.
- Identity and discovery: `get_me`, `search`, `list_projects`.
- Notebook inspection: `get_notebook`.
- Notebook editing: `create_project`, `create_notebook`, `create_block`, `update_block`, `reorder_notebook_blocks`.
- Integrations: `list_integrations`, `get_integration`, `list_integration_project_usages`, `list_integration_notebook_usages`, `list_integration_block_usages`.
- Execution: `create_run`, `list_notebook_runs`, `get_run`.
- Docs: `list_docs`, `get_doc`.
## Route By Intent
| User asks for | Use |
| --- | --- |
| Workspace overview, heartbeat, active/scheduled notebooks, broad inventory | `get_me`, `list_projects`, `list_integrations`, and [references/workspace-summary.md](references/workspace-summary.md) |
| Notebook contents, inputs, SQL, blocks, outputs, review, or explanation | `deepnote-notebooks` |
| Project/notebook creation, adding cells, updating cells, moving/reordering cells, scaffolded notebook content | `deepnote-notebook-editing` |
| Notebook execution, run status, recent/failed runs, run history, snapshots, integration usage, cached tables/columns | `deepnote-data-execution` |
| Project, notebook, workspace, or share links | `deepnote-links` |
| Product docs or how-to questions | `list_docs`, then `get_doc` |
## Routing Defaults
1. Resolve ambiguous names and IDs with `search`, `list_projects`, or `list_integrations`.
2. Use `get_me` when workspace identity, connected user, caller role, or OAuth context matters.
3. Read with `get_notebook` before reasoning about notebook blocks, inputs, latest run metadata, or before editing notebook structure.
4. Use `get_integration` for cached table, schema, column, or table-existence questions about an integration.
5. Use `list_notebook_runs` for run history or failed-run searches; use `get_run` for one selected run's status, errors, or snapshot.
6. Use specialist skills for any workflow with detailed rules. Keep this skill as the router.
## Global Guardrails
- Never expose tokens, secret values, raw credentials, or sensitive integration metadata. Refer to secret names only.
- Treat project creation, notebook creation, block creation, block updates, block reordering, and notebook runs as persistent or stateful actions. Resolve targets carefully and report affected IDs.
- Do not run a notebook unless the user asks for execution, clearly needs fresh results, or confirms a creation workflow's final run prompt. Creation workflows may ask whether to run the newly created notebook, but must not run it preemptively. Run input overrides apply only to that run.
- Do not expose `snapshotDownloadUrl` values unless the user asks for a download/file handoff; use inline snapshots only when output or error details are needed.
- Use cached integration structure when available, but do not claim a fresh live database scan, row preview, single-block execution, environment mutation, permission change, publishin
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
deepnote-data-apps11.7 KB
View saved version →
---
name: deepnote-data-apps
description: Use when creating, changing, testing, or publishing a Deepnote data app project, a web page in `_deepnote_static/index.html` backed by one notebook.
---
# Deepnote Data Apps
Tool arguments and the capability boundary are defined in `deepnote-mcp`. Notebook edits follow `deepnote-notebooks`, runs follow `deepnote-runs`, and links follow `deepnote-links`.
A data app project has two parts: the page, a responsive HTML page in `_deepnote_static/index.html` that can load its own CSS, JavaScript, and images from that folder, and one notebook that runs the SQL and Python behind it.
## Creating An App
1. Create the project with `create_project` and `projectType: "data_app"`. It starts with its notebook and a placeholder page, with sharing and viewer API access already on; do not change them. Never add a page to a project of another type or publish one with the Deepnote CLI's `deepnote publish`; those are the legacy static sites.
2. Look for data in the project's integrations and files first, then build a small, polished first version. If nothing fits, use clearly labeled sample data and offer to connect real data, unless the user named specific data: then ask where it is.
## The Notebook
- Keep one short block that computes only the data the page needs and displays it as the notebook's only JSON output:
```python
import json
from IPython.display import display
app_data = {'rows': json.loads(df.to_json(orient='records', date_format='iso'))}
display({'application/json': app_data}, raw=True)
```
- Queries, heavy computation, credentials, and authenticated calls stay in the notebook. The page only filters, sorts, and charts.
- The app's controls are the notebook's input blocks. Reuse them by name and add only the missing ones.
- For AI-written text, such as a summary of the data, keep an agent block as the last block and ask for that text in its prompt. The page reads it as `agentBlockSummary`.
- The page shows each viewer's own newest successful detached run, or, in a public app without private outputs, the editors' newest one until the viewer runs it, so running blocks in the editor changes nothing. After changing the notebook, start a run with `create_run` and `detachedRunStorageMode: "readonly"`, wait until `get_run` with `snapshotDelivery: "blocks"` reports success, and check the JSON output's keys, types, and first rows before wiring the page to it. Changes to the page alone need no new run.
## The Page
- `index.html` can load other files from `_deepnote_static/` by relative path, such as `styles.css`, `app.js`, or `logo.svg`. Keep the app client script and the Tailwind setup below in `index.html`, and move the rest into files of their own when that keeps the page easier to change.
- Keep a local copy of `_deepnote_static/` in a folder of its own. Read each file the page loads or you will change with `read_file` once, unless you wrote it in this conversation; `get_project` lists them. Images that `read_file` cannot read show as broken in the local preview. Edit the files there, and once the page works in the local preview in Testing, push each new or changed file with `write_file` at its path under `_deepnote_static/` and `overwrite: true`. Where you cannot run local commands, write the files with `write_file` directly. When the app existed before this conversation, ask the user before the first push whether to update it in Deepnote, with the preview URL when there is one: pushing overwrites the app for good, and viewers of a published app see the change at once. Once they agree, push later changes they ask for in this conversation without asking again.
- Start the `<head>` of `index.html` with `<script src="https://deepnote.com/static/app-client/v1.js"></script>`, before any other script, and load CDN scripts with `crossorigin="anonymous"`. The script exposes `Deepnote.connect()`, not React components or `DeepnoteApp`.
- Style the page with Tailwind CSS 4.3.3. After thPreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
deepnote-data-execution8.91 KB
View saved version →
---
name: deepnote-data-execution
description: Use when running Deepnote notebooks, inspecting notebook inputs, reviewing integration references and cached table structure, listing run history, or interpreting run status and snapshot outputs through the Deepnote app tools.
---
# Deepnote Data And Execution
## Available Context
Use the connected Deepnote app tools for the execution and context they currently expose:
- `get_notebook` for notebook blocks, input variables, last-run metadata, and integration references visible in blocks.
- `list_integrations` for workspace integration names and types.
- `get_integration` for integration details and cached table structure, optionally filtered by `databaseName`, `schemaName`, or exact `tableName`.
- `list_integration_project_usages`, `list_integration_notebook_usages`, and `list_integration_block_usages` for direct integration usage mapping.
- `create_run` to start full-notebook execution, optionally with input values.
- `list_notebook_runs` for historical notebook runs, newest first, with `pageSize` and `pageToken` pagination.
- `get_run` for run status, errors, completion time, and run snapshots. When `snapshotDelivery` is omitted, it returns a short-lived `snapshotDownloadUrl` when a snapshot is available; this is equivalent to `snapshotDelivery: "downloadUrl"`. Request `snapshotDelivery: "inline"` only when you need `snapshotContent` in the tool response.
- `get_me` for the authenticated workspace, connected user, and caller access level when execution permissions or workspace identity matter.
Use `get_integration` for cached table and column structure when the user asks about integration schemas, tables, columns, or whether a table exists. Do not claim live database introspection, table previews, query previews, file metadata, or environment configuration unless a current Deepnote app tool explicitly exposes that data.
## Execution Workflow
1. Read the notebook context first with `get_notebook`.
2. Identify whether the user needs a fresh run, a specific run status, or notebook run history.
3. If the notebook has inputs and the user supplied values, map values to the exact input `name` fields returned by `get_notebook`.
4. Check whether execution may mutate data, call external services, trigger schedules, or consume significant compute.
5. Use `create_run` only for full-notebook execution by `notebookId`; the Deepnote app does not currently expose single-block execution.
6. If `create_run` returns a tool error, report that error and stop; do not call `get_run` unless a run ID was returned.
7. Use `get_run` to inspect status, errors, completion time, and snapshot availability before reporting results. For routine status checks, omit `snapshotDelivery` so the default download URL delivery is used; request `snapshotDelivery: "inline"` when you need to inspect notebook outputs, snapshot errors, or result details.
Before starting a run, inspect the notebook for cells that print environment variables, secrets, credentials, or entire configuration objects. If found, warn the user and get explicit confirmation before running. Also warn before running notebooks that start servers, send bulk requests, call external services, or mutate data.
## Run History
Use `list_notebook_runs` when the user asks about recent runs, failed runs, run history, or anything older than the latest run metadata returned by `get_notebook`. The tool returns runs newest first with `runId`, `notebookId`, `status`, `createdAt`, `completedAt`, and `pagination`.
For short history requests, call `list_notebook_runs` with the default `pageSize` of 20. For broader audits, use `pageSize: 100` and follow `pagination.nextPageToken` while `pagination.hasMore` is true, stopping once you have enough evidence for the user's question.
Use `get_run` only after selecting a specific run that needs detail, snapshot availability, output inspection, or failure debugging. If the user asks "why did the last run fail?" and no
Preview of the first 4,000 characters. Read full instructions →
deepnote-links5.8 KB
View saved version →
---
name: deepnote-links
description: Use when a task asks for Deepnote URLs, links, project links, notebook links, workspace links, share links, UTM/campaign links, or when a Deepnote response should include clickable links built from MCP project, notebook, or workspace data.
---
# Deepnote Links
Use this skill to build user-facing Deepnote web links from MCP data. Prefer `generate_project_url`, then links grounded in `get_me`, `list_projects`, `search`, and `get_notebook` responses. Every project and notebook link must include the UTM parameters below.
## Server-Generated Links
Use `generate_project_url` as the preferred source for a single project or notebook URL, then append the UTM parameters below. Fall back to the manual URL shapes when the tool is unavailable, when building many links from one `list_projects` or `search` response, or when a workspace link is needed.
Do not retry `Project not found` or `Notebook not found` errors with guessed IDs. When both IDs are supplied, the notebook must belong to the project.
## Inputs To Resolve
1. Call `get_me` when workspace-aware links are useful. Use `workspace.id` and `workspace.slug`; do not use the API key name, bearer token, or user email in links or summaries.
2. Resolve the project with `list_projects` or `search`. Use the project `id`, `name`, and `slug` if the MCP response exposes one.
3. Resolve notebook links with `get_notebook` when possible. Use the notebook `id`, `name`, and parent project data.
4. If the exact project or notebook is ambiguous, ask a short clarification or provide a compact candidate list with links only for unambiguous matches.
## Links After Creation
Link the active notebook as defined by the Active Notebook Rule in `deepnote-notebooks`: the notebook returned by `create_notebook` when one was called, otherwise the default notebook of the project returned by `create_project`. If parent project data is missing for that notebook, call `get_notebook` for its ID or use the project ID from the creation workflow before building the link.
## URL Shapes
Use the production web origin `https://deepnote.com` for Deepnote MCP links. Do not derive the web origin from API or MCP hosts.
Prefer workspace-scoped links when `get_me` returns both `workspace.slug` and `workspace.id`:
```text
workspaceSlugWithId = {workspace.slug}-{workspace.id}
workspace link = {origin}/workspace/{workspaceSlugWithId}
project link = {origin}/workspace/{workspaceSlugWithId}/project/{projectSegment}
notebook link = {origin}/workspace/{workspaceSlugWithId}/project/{projectSegment}/notebook/{notebookSegment}
```
If workspace data is not available, use the non-workspace project route:
```text
project link = {origin}/project/{projectSegment}
notebook link = {origin}/project/{projectSegment}/notebook/{notebookSegment}
```
## Slug Segments
Use the most canonical segment available:
1. If the MCP response exposes a `slug`, use it.
2. Otherwise, for simple names, build a readable segment as `{slugifiedName}-{id}`.
3. If exact slugification is uncertain, the name is missing, or the name has unusual characters, use the ID alone.
Deepnote project routing accepts UUID-only project segments, so `{project.id}` is the safest fallback. Notebook routing uses ID-only segments when a notebook name is not available, so `{notebook.id}` is the safest notebook fallback.
Deepnote's readable slugs are created with strict slugification: spaces become hyphens, `/` becomes `-`, unsafe characters are stripped or normalized, and case is preserved. Examples:
```text
Subject Tracker + 0508fc64-b2c8-4982-b6a0-2590c94b6000
=> Subject-Tracker-0508fc64-b2c8-4982-b6a0-2590c94b6000
folder/notebook 10% + a1b2c3d4
=> folder-notebook-10percent-a1b2c3d4
```
## Optional Suffixes
- File paths, when exposed and requested, append after the project segment as `/{encodeURIComponent(filePath)}`.
- Cell or block anchors append after the UTM query string as `#anchor`.
- Use Streamlit URLs returned by `create_stPreview of the first 4,000 characters. Read full instructions →
deepnote-mcp17.8 KB
View saved version →
---
name: deepnote-mcp
description: Use when a task mentions Deepnote, the Deepnote MCP server, Deepnote docs, projects, workspaces, notebooks, blocks, integrations, API keys, files, apps, or notebook runs. Shared rules for all Deepnote skills.
---
# Deepnote MCP
## When To Use Deepnote
Use the Deepnote MCP server as the primary interface for hosted Deepnote state. Prefer it over browser automation, screenshots, ad hoc HTTP calls, or local filesystem guesses whenever the user asks about Deepnote projects, notebooks, blocks, integrations, files, apps, search, or notebook runs. The one exception is previewing a data app page locally with the script in `deepnote-data-apps`.
If the Deepnote MCP server is not available in the current session, say that clearly and ask the user to connect or configure it. The hosted endpoint is `https://deepnote.com/mcp`; it accepts an OAuth sign-in or a Deepnote personal API key sent as a bearer token. Do not pretend to have inspected Deepnote state.
The plugin registers the hosted server under the MCP server id `deepnote`.
## Tool Catalogue
This is the authoritative summary of tool arguments. Workflow skills add only the constraints needed for their tasks.
- `get_me`: return the calling API key, creator user, workspace, and workspace access level.
- `search`: search workspace resources across projects, notebooks, blocks, and integrations.
- `list_folders`: list all workspace folders and their `parentFolderId` relationships, optionally filtered by `nameContains`.
- `list_projects`: list workspace projects, optionally filtered by name, with cursor pagination (`pageSize`, `pageToken`, `pagination.nextPageToken`, `pagination.hasMore`). Notebook rows expose `isInit`, `isScheduled`, and `lastRunAt`.
- `get_project`: get a project's type, folder, notebooks, attached integration summaries, recursive file inventory, data app settings (`dataApp` with `published` and `url`, `null` when the project is not a data app), and environment (Docker image) by `projectId`. `environment` is `null` when the project builds its image from a Dockerfile or has none set. `dataApp.published` doesn't say whether the app is public; MCP can't see that.
- `list_environments`: list the environments (Docker images) projects in the workspace can run on, Deepnote's and the workspace's custom ones, in one unpaginated response. Each has `id`, `name`, `image`, `type` (`deepnote` or `custom`), `language` (`python` or `r`), `isDefault` (one CPU and one GPU default), `isGpu`, and `isDeprecated`; deprecated environments keep working for projects already on them but should not be chosen. A custom image from a private registry is pulled only when its registry integration is attached to the project.
- `list_integrations`: list workspace integrations, optionally filtered by name or type.
- `get_integration`: get integration details and cached table structure, optionally filtered by `databaseName`, `schemaName`, or exact `tableName`. For large integrations, `search` takes a natural-language description and returns only the 20 most relevant tables.
- `list_integration_project_usages`: list projects connected to an integration, optionally narrowed to one `projectId`.
- `list_integration_notebook_usages`: list notebooks that contain SQL blocks using an integration, optionally narrowed to one `projectId`.
- `list_integration_block_usages`: list SQL blocks using an integration, optionally narrowed to one `projectId`.
- `create_integration`: create a workspace integration of an API-creatable type. Requires `name`, `type`, and connection `metadata`; requires workspace integration-management permission. The response repeats `metadata`, which can contain credentials.
- `attach_integration`: attach an integration to a project. Requires `integrationId` and `projectId`; returns a conflict if already attached.
- `detach_integration`: detach an integration from a project. Requires `integrationId` and `projectId`; returns a conflict if not attached.
- `
Preview of the first 4,000 characters. Read full instructions →
deepnote-notebook-editing8.19 KB
View saved version →
---
name: deepnote-notebook-editing
description: Use when creating Deepnote projects or notebooks, adding or updating blocks or cells, moving existing blocks, scaffolding notebook content, inserting SQL/code/markdown/input blocks, or otherwise editing notebook structure through the Deepnote app tools.
---
# Deepnote Notebook Editing
## When To Use
Use this skill when the user asks to create a Deepnote project, create a notebook, add a block or cell, update an existing block or cell, move or reorder existing blocks, scaffold starter notebook content, insert code, SQL, markdown, or input blocks, or make a structural notebook edit supported by the current Deepnote app write tools.
This workflow requires the connected Deepnote app to expose the write tools needed for the requested edit. Use `create_project`, `create_notebook`, and `create_block` for creation workflows; use `update_block` for changing existing block content or SQL integration; use `reorder_notebook_blocks` for moving existing blocks. If the required tool is not visible in the current session, do not claim editing support; explain which app tool is missing.
The editing surface covered by this skill is:
- `create_project`: create a new project. Requires `name`; accepts optional `folderId`.
- `create_notebook`: create an empty notebook in a project. Requires `projectId`; accepts optional `name`.
- `create_block`: create a block in a notebook. Requires `notebookId` and `type`; accepts optional `content`, `metadata`, `position`, `includeNotebookBlockIds`, and SQL-only `integrationId`.
- `update_block`: update an existing block. Requires `blockId`; accepts `content`, SQL-only `integrationId`, or both. At least one of `content` or `integrationId` is required.
- `reorder_notebook_blocks`: move one or more existing blocks in a notebook. Requires `notebookId`, non-empty unique `blockIds` in the desired moved-block order, and `placement`.
## Editing Workflow
1. Resolve ambiguous names and IDs before writing. Use `get_me` for workspace identity, `search` or `list_projects` for projects/notebooks, `get_notebook` for current block order, and `list_integrations` for SQL connections.
2. Treat `create_project`, `create_notebook`, and `create_block` as non-idempotent. Repeating the same call creates another resource.
3. Use `create_project` only when the user wants a new project. A created project includes a default empty notebook; if the workflow later calls `create_notebook`, the new `create_notebook` result becomes the active notebook for blocks, verification, links, and run prompts.
4. Use `create_notebook` only when adding an empty notebook to a project. It does not accept starter blocks; capture the returned notebook ID and create blocks afterward with `create_block` in that exact notebook.
5. Use `create_block` for each new block. Omit `position` to append, or pass a zero-based `position` when placement matters.
6. Use `update_block` when changing an existing block. It updates content and/or SQL integration in place; it does not create a new block.
7. Pass `includeNotebookBlockIds: true` when the final block order matters, especially for ordered inserts or multi-block scaffolds.
8. Use `reorder_notebook_blocks` when moving existing blocks. It preserves the relative order of blocks omitted from `blockIds` and returns the final active block order.
9. Verify meaningful edits with `get_notebook` after block creation, block update, or block reordering when order, integration attachment, or multi-block content matters.
10. Do not run the notebook after editing unless the user explicitly asks for execution or confirms a final run prompt. After creating or scaffolding a notebook, ask whether to run that exact notebook in Deepnote.
## Creation Target Tracking
For creation workflows, keep one active target notebook:
- If only `create_project` is called, use the default notebook created with the project as the active notebook when blocks or a notebook link are needed.
- If `c
Preview of the first 4,000 characters. Read full instructions →
deepnote-notebooks11.5 KB
View saved version →
---
name: deepnote-notebooks
description: "Use when reading or reviewing Deepnote notebooks, creating or deleting projects or notebooks, renaming or duplicating notebooks, and creating, editing, deleting, or reordering blocks through the Deepnote MCP server."
---
# Deepnote Notebooks
Tool arguments are defined in `deepnote-mcp`. Running a notebook is `deepnote-runs`. Links follow `deepnote-links`.
## Inspection Workflow
1. Resolve the target notebook with `search` or project context before using `get_notebook`.
2. Read the notebook with `get_notebook` before answering questions about structure, inputs, blocks, or last-run state.
3. Preserve the distinctions between block types, notebook inputs, code, SQL, markdown, and metadata in your reasoning.
4. When reporting inputs, include the input `name`, `type`, current `value`, and `label` when useful.
5. Call `get_block` when one block's `metadata` (input configuration, callout color, todo state) or its current output in the editor matters; `get_notebook` returns neither. Pass `includeOutputs: true` for the output, and `fullOutputs: true` only when the user needs a long output whole.
6. When SQL connection usage matters, confirm it with `get_block`, `list_integrations`, and the integration usage tools in `deepnote-workspace` instead of inferring from names; use `get_integration` for cached table and column context.
7. Ground reviews and explanations in specific notebook or block names and IDs when useful.
8. For recent, failed, or historical runs, use `deepnote-runs`.
## Inspection Output
Help the user decide what the notebook does, whether it is safe to run, and what to do next. Lead with the answer, then include only the tables or cautions that materially help. Omit exhaustive block listings, raw code, and long outputs unless asked.
1. Start with a one-sentence brief: `Notebook "Name" in project "Project" has 12 blocks, 2 inputs, 1 visible connection, and last ran successfully on YYYY-MM-DD HH:MM UTC.`
2. Show a compact status table:
| Field | Value |
| --- | --- |
| Project | `Project name` |
| Notebook | `Notebook name` |
| Notebook ID | `notebook-id` |
| Scheduled | `Yes` or `No` |
| Last Run | `status/date/run id` or `No run visible` |
| Visible Connections | `Integration name (type)` or `None visible via MCP` |
3. If inputs exist, add an inputs table:
| Input | Type | Current Value | Label |
| --- | --- | --- | --- |
| `input_name` | `text` | `safe summary or value` | `Human label` |
4. Add a block map when useful, especially for reviews and debugging:
| Order | Type | Purpose | Connection / Output |
| --- | --- | --- | --- |
| `1` | `sql` | `SELECT demo.gapminder sample` | `Clickhouse (clickhouse)` |
5. Add `Cautions` only when actionable: cells that print secrets, environment variables, or configuration objects, hard-coded credentials, mutating external calls, long-running servers, large dataset dumps, missing inputs, failed or pending last runs, SQL blocks whose integration is not visible, or integration usage that was not checked when it matters.
6. End with `Useful Next Actions` only when it helps: run the notebook, inspect the latest run, list recent runs, map integrations, summarize outputs, or review risky cells.
Keep raw code excerpts short; summarize large cells and mention block IDs when useful. If execution was not run, say so plainly and mention the remaining risk. For larger reviews, summarize relevant sections rather than listing every block.
## Code Guidance
- Before suggesting code changes, inspect nearby blocks for imports, shared variables, SQL connections, inputs, and upstream assumptions.
- Prefer deterministic notebook code. Avoid hidden global state, implicit external files, or hard-coded credentials.
- For SQL blocks, preserve the existing connection or data source in recommendations unless the user asks to move it.
- Do not claim an edit was applied unless a write tool is available and reported success.
## Editing Workflow
Use this
Preview of the first 4,000 characters. Read full instructions →
deepnote-runs7.3 KB
View saved version →
---
name: deepnote-runs
description: Use when running a Deepnote notebook, passing run input values, checking run status, listing or auditing run history, debugging a failed or stuck run, or reading run snapshot outputs through the Deepnote MCP server.
---
# Deepnote Runs
Tool arguments, pagination, and the capability boundary are defined in `deepnote-mcp`. Integration structure and usage are in `deepnote-workspace`.
## Execution Workflow
1. Read the notebook first with `get_notebook`.
2. Identify whether the user needs a fresh run, a specific run's status, or run history.
3. If the notebook has inputs and the user supplied values, map them to the exact input `name` fields from `get_notebook` (see Run Inputs).
4. Before starting a run, inspect the notebook for cells that print environment variables, secrets, credentials, or entire configuration objects, and for cells that start servers, send bulk or network requests, write files, call external or production-like systems, or mutate data. Name the risk and get explicit confirmation before running.
5. Use `create_run` by `notebookId`; detached full-notebook execution is the default. Targeted execution updates the live editor session, so do it only when the user asks: set `detached: false` and pass a non-empty unique `blockIds` list. Set `runDependentBlocks: true` only with `blockIds` when downstream blocks should run too.
6. If `create_run` returns an error, report it and stop. Do not call `get_run` unless a run ID was returned. This includes user-facing errors such as workspace or parallel run limits.
7. Poll `get_run` until the run reaches a terminal state or it is clear the run is still in progress, following Snapshot Delivery below.
## Machines
- Detached runs, the default, start a machine of their own. To size one for the workload, call `list_machine_types`, pick an `available` type with enough `vCpus`, `memoryGiB`, or `gpuCount`, and pass its `id` as `machineType` to `create_run`. The project's machine type stays the same.
- Live runs (`detached: false`) use the project machine and start it when it is stopped. Use `get_machine` to check its status and size, `start_machine` to have it ready ahead of time, and `restart_machine` when it is in the `error` status. After a restart, a stop, or an idle shutdown the kernel is fresh, so rerun the blocks that set up the state first.
- To make the project machine bigger or smaller for live work, use `update_machine` with `type`. On a running machine this needs `restart: true`, which clears kernel state, so ask first. A custom machine type only works for projects in its sandbox environment; when the project is in another one, also pass the type's `sandboxEnvironmentId` from `list_machine_types`.
- Read the machine size from `get_machine`, not from code such as `os.cpu_count()`, which reports the host's cores rather than the machine's.
## Run Inputs
`create_run` accepts an optional `inputs` object. Keys must be notebook input names from `get_notebook`, not labels or block IDs. Values must match the input block type:
- Text, textarea, file, date, slider, and single-select inputs use strings. Slider values are numeric 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.
If the user gives a label instead of a name, map it to the closest input `name` only when the match is unambiguous; otherwise ask. An undefined input name or a mismatched value type makes Deepnote reject the run with a validation error. Run input values apply to that run only and never change the notebook's saved defaults.
## Run History
Use `list_notebook_runs` for recent runs, failed runs, run history, or anything older than the latest run metadata in `get_notebook`. For short requests, keep the default page size; for audits, page through all results. Use `get_run` only after selecting a specific run that needs detail. For "why did the last run fail?" without
Preview of the first 4,000 characters. Read full instructions →
deepnote-streamlit-apps4.42 KB
View saved version →
---
name: deepnote-streamlit-apps
description: Use when creating, changing, testing, or checking a Deepnote Streamlit app project, a Python Streamlit app in `app.py` backed by one notebook.
---
# Deepnote Streamlit Apps
Tool arguments and the capability boundary are defined in `deepnote-mcp`. Notebook edits follow `deepnote-notebooks`, runs follow `deepnote-runs`, and links follow `deepnote-links`.
A Streamlit app project has two parts: the app, Python code in `app.py` hosted on the project machine, and one notebook for exploring data and testing code.
## Creating An App
1. Create the project with `create_project` and `projectType: "streamlit_app"`. It starts with its notebook and a placeholder `app.py` that is already served, with viewer API access already on.
2. Get the app ID and URL from `list_streamlit_apps`. Do not call `create_streamlit_app`; the project serves one app.
3. Look for data in the project's integrations and files first, then build a small, polished first version. If nothing fits, use clearly labeled sample data and offer to connect real data, unless the user named specific data: then ask where it is.
## Writing The App
- Replace `app.py` with `write_file` and `overwrite: true`, sending the whole file. The app reloads when its code changes.
- Read the current `app.py` with `read_file` before changing it, unless you wrote it in this conversation.
- Use the notebook to explore data and test queries before moving them into the app. The app runs separately and can't see the notebook's variables, so it loads its own data.
- To query an integration attached to the project, call `deepnote_toolkit.set_integration_env()` at the top of the app, then `deepnote_toolkit.execute_sql(query, 'SQL_<INTEGRATION_ID>')` with the integration ID uppercased and dashes replaced by underscores. For OAuth integrations, use `get_snowflake_connection(integration_id)` or `get_bigquery_client(integration_id)` from `deepnote_toolkit.streamlit_data_apps`, so each viewer sees data with their own access.
- Every interaction reruns the whole script, so cache data loading. `@st.cache_data(ttl=...)` is shared by all viewers, so use it only for data that is the same for everyone; keep data from OAuth integrations in `st.session_state`.
- Start the app with `st.set_page_config(layout="wide")`, put filters in `st.sidebar`, and show key numbers with `st.metric` in `st.columns`. Lay out dashboards as a title with one line of context, filters, a row of key numbers, one to three main charts, then a detail table. Format numbers and dates for reading, and label units.
- For AI-written text, such as a summary of the data, keep an agent block as the last block of the notebook and ask for that text in its prompt. In the app, compute `StreamlitCloudRunner('<notebook ID>').run({}).agent_text()` from `deepnote_toolkit.streamlit` once per session in `st.session_state` and show it with `st.markdown`. It runs the notebook as the viewer through the app's API access.
- The theme is in `.streamlit/config.toml` next to `app.py`. Keep the Deepnote-like default unless the user asks for another look. Colors apply on the next rerun; font changes may need an app restart.
- Never put secrets or credentials in the app's code.
## Testing
1. Run the app in a scratch code block with `at = AppTest.from_file('/work/app.py', default_timeout=60).run()` from `streamlit.testing.v1`, and print `at.exception` and `at.error`. Run the block with `create_run`, `detached: false`, and its ID in `blockIds`, and read the output with `get_run` and `snapshotDelivery: "blocks"`. Fix what it reports, since the app keeps running when its script fails, and delete scratch blocks when done.
2. Poll `get_streamlit_app_status` until it reports `running`. `starting` does not distinguish a slow boot from a crashed app; if it does not reach `running`, report the last status and suggest checking the app logs in Deepnote. Do not probe the app URL itself.
## Constraints
- The project has one notPreview of the first 4,000 characters. Read full instructions →
deepnote-workspace8.58 KB
View saved version →
---
name: deepnote-workspace
description: "Use for Deepnote workspace and project operations: summaries, project and folder inventories, project inspection, integrations and their usage, cached table structure, and reading, writing, copying, or deleting project files."
---
# Deepnote Workspace
Tool arguments, pagination, and the capability boundary are defined in `deepnote-mcp`. Build links with `deepnote-links`.
## Workspace Summary Workflow
When the user asks for a workspace summary, heartbeat, overview, or which notebooks are active or scheduled:
1. Use `get_me` for workspace name, workspace ID, API key type, and caller access level when useful.
2. Use `list_projects` to collect projects and notebooks. For complete inventories, page through all results.
3. Use `list_integrations` to collect integration names, types, and IDs.
4. Use `get_notebook` for notebooks that need block, input, or recent-run detail.
5. Identify scheduled notebooks from `isScheduled`.
6. Identify active notebooks from `lastRunAt` or an explicitly requested run status from `get_run`. `get_machine` reports the project machine's state, not open editor sessions. Say that active means recent run activity rather than an open editor session. Prefer `recently run`, `scheduled`, `pending run`, or `last run` over "currently open" or "currently running".
7. Map integration usage with the usage tools when direct usage matters. If usage was not checked, write `Usage not checked`; if a checked usage tool returns nothing, write `None found`.
8. Build project and notebook links with `deepnote-links`, using `utm_term=workspace_summary` for links created by this workflow rather than by a single tool result.
## Workspace Summary Output
Workspace-status output should read like a small operations dashboard:
1. Start with a one-sentence health line, for example: `Deepnote workspace is reachable; the current MCP response includes 6 projects, 15 notebooks, 1 scheduled notebook, and 4 integrations.`
2. Add a compact `Key Signals` list with counts visible in the current MCP response: projects, notebooks, scheduled notebooks, recently run notebooks, failed or pending runs when checked, and integrations.
3. Use the summary table below as the main artifact: one row per notebook, grouped by project.
4. Keep integrations inside the table as an `Integrations` column. Use a standalone integration table only when the user explicitly asks for an integration inventory or usage report.
5. Hyperlink project and notebook names. The notebook name is the link label.
6. Finish with `Notable Findings` only when something is actionable: a scheduled notebook with no last run, a pending or failed run, a notebook that prints environment variables, or an integration with no checked usage.
Summary table, for workspace summaries, notebook inventories, project breakdowns, and "which notebooks do I have?" requests:
| Project | Notebook | Scheduled | Last Run Seen | Integrations |
| --- | --- | --- | --- | --- |
| [Project name](project URL with UTM parameters) | [Notebook name](notebook URL with UTM parameters) or `N more notebooks` | `Yes` or `No` | `YYYY-MM-DD HH:MM UTC`, `None seen`, or `Not visible via MCP` | `Integration name/Type` or `None found` |
Row rules:
- For a specific project or notebook, filter the table to it.
- For large workspaces, keep individual rows for scheduled notebooks, recently run notebooks, and notebooks with visible integrations, then collapse each project's remaining notebooks into one `N more notebooks` row. A collapsed row is `No` for Scheduled, shows the most recent visible `lastRunAt` among its notebooks or `None seen`, and lists their integrations, `None found` when usage was checked, or `Usage not checked`.
- `Last Run Seen` is the notebook's visible `lastRunAt`, or a checked `get_run` completion time when more current. Format dates in UTC as `YYYY-MM-DD HH:MM UTC`. Never write `None seen` when a run ID or run timestamp is visible.
- `Integrations` uses na
Preview of the first 4,000 characters. Read full instructions →