@@ -1,13 +1,13 @@
 # Deepnote Codex Plugin
 
-Use Deepnote from Codex to search workspaces, inspect notebooks, list integrations, start notebook runs, and summarize run status and outputs.
+Use Deepnote from Codex to identify the current workspace, search resources, inspect notebooks, list projects and integrations, map integration usage, read Deepnote docs, start notebook runs, and summarize run status and outputs.
 
 ## What Is Included
 
 - 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, notebook inspection, and notebook execution workflows
+- Deepnote skills for workspace search, docs lookup, integration mapping, notebook inspection, and notebook execution workflows
 - Deepnote branding assets
 
 ## Requirements
@@ -60,15 +60,21 @@ This marketplace marks authentication as `ON_INSTALL`, so Codex may show Deepnot
 The hosted Deepnote MCP server currently exposes these tools:
 
 - `search`: search workspace resources across projects, notebooks, blocks, and integrations
-- `list_projects`: list workspace projects, optionally filtered by name
+- `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_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 notebook editing, 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 search workspace resources, list projects and integrations, inspect notebooks, 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](https://deepnote.com/docs/deepnote-api).
+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, 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](https://deepnote.com/docs/deepnote-api).
 
 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.
 
@@ -78,7 +84,7 @@ Workspace status and heartbeat responses should read like a compact operations d
 | --- | --- | --- | --- | --- |
 | `Project name` | `Notebook name` | `Last run: YYYY-MM-DD HH:MM UTC` or `No recent run visible` | `Yes` or `No` | `Integration name (type)` or `None visible via MCP` |
 
-For large workspaces, Codex should include active notebooks, scheduled notebooks, and notebooks with visible linked connections first, then summarize remaining notebooks by count.
+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:
 
@@ -88,10 +94,39 @@ Notebook inspection responses should help the user understand purpose, safety, a
 | Notebook | `Notebook name` |
 | Scheduled | `Yes` or `No` |
 | Last Run | `status/date/run id` or `No run visible` |
-| Visible Connections | `Integration name (type)` or `None visible via MCP` |
+| Visible Connections | `Integration name (type)`, `Usage not checked`, or `None visible via MCP` |
 
 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.
 
+## Workspace Identity And Project Pagination
+
+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:
+
+```json
+{
+  "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.
+
+## Integration Usage Mapping
+
+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`.
+
 ## Run Notebooks With Inputs
 
 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`.
@@ -119,6 +154,8 @@ Input values must match the notebook input block type:
 
 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.
+
 ## Install From GitHub
 
 After this repo is pushed to GitHub, add it as a Codex marketplace:
@@ -185,17 +222,21 @@ codex plugin marketplace upgrade deepnote
 ## Good First Prompts
 
 - `Search my Deepnote workspace for customer retention notebooks.`
+- `Which Deepnote workspace am I connected to?`
 - `Inspect this Deepnote notebook and summarize its inputs.`
 - `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.`
 
 ## Troubleshooting
 
 - 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 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 edit or environment change, remember that the current hosted MCP server is read/search plus full-notebook execution only.
+- If Codex suggests an edit or environment change, remember that the current hosted MCP server is read/search/docs/usage mapping plus full-notebook execution only.
 
 ## License
 
 
@@ -1,7 +1,7 @@
 {
   "name": "deepnote",
-  "version": "0.1.0",
-  "description": "Search Deepnote workspaces, inspect notebooks, list integrations, and run notebooks from Codex.",
+  "version": "0.1.1",
+  "description": "Search Deepnote workspaces, inspect notebooks, map integrations, read docs, and run notebooks from Codex.",
   "author": {
     "name": "Deepnote",
     "url": "https://deepnote.com"
@@ -21,8 +21,8 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Deepnote",
-    "shortDescription": "Work with Deepnote projects and notebooks from Codex.",
-    "longDescription": "Adds Deepnote skills and hosted MCP configuration for Codex. Use it to search workspace resources, list projects and integrations, inspect notebook structure and inputs, start notebook runs with optional input values, and summarize run status and outputs.",
+    "shortDescription": "Work with Deepnote workspaces, projects, notebooks, and docs from Codex.",
+    "longDescription": "Adds Deepnote skills and hosted MCP configuration for Codex. Use it to identify the current workspace, search resources, list paginated projects and integrations, map integration usage, inspect notebook structure and inputs, read Deepnote docs, start notebook runs with optional input values, and summarize run status and outputs.",
     "developerName": "Deepnote",
     "category": "Productivity",
     "capabilities": [
@@ -35,6 +35,7 @@
     "termsOfServiceURL": "https://deepnote.com/terms",
     "defaultPrompt": [
       "Search my Deepnote workspace.",
+      "Which Deepnote workspace am I connected to?",
       "Inspect this Deepnote notebook.",
       "Run a Deepnote notebook with inputs."
     ],
 
@@ -11,8 +11,10 @@ Use the Deepnote MCP server for the execution and context it currently exposes:
 
 - `get_notebook` for notebook blocks, input variables, last-run metadata, and integration references visible in blocks.
 - `list_integrations` for workspace integration names and types.
+- `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.
 - `get_run` for run status, errors, completion time, and snapshot content when available.
+- `get_me` for the authenticated workspace, API key type, and caller access level when execution permissions or workspace identity matter.
 
 Do not claim direct access to database schemas, table previews, file metadata, query previews, or environment configuration unless a current MCP tool explicitly exposes that data.
 
@@ -23,7 +25,8 @@ Do not claim direct access to database schemas, table previews, file metadata, q
 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 hosted MCP server does not currently expose single-block execution.
-6. Use `get_run` to inspect status, errors, completion time, and snapshot content before reporting results.
+6. If `create_run` returns an MCP 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 content before reporting results.
 
 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.
 
@@ -49,7 +52,7 @@ The hosted Deepnote MCP server currently does not expose environment mutation to
 
 ## Reporting Results
 
-For successful runs, include the executed notebook name or ID, run ID, status, any input overrides that are safe to mention, and the important result from snapshot content when available. For failures, include concise error detail and the next fix to try. Avoid pasting long logs unless the user asks for them.
+For successful runs, include the executed notebook name or ID, run ID, status, any input overrides that are safe to mention, and the important result from snapshot content when available. For failures, include concise error detail and the next fix to try. If a run fails before it starts, such as a workspace or parallel run limit, report the user-facing API error directly. Avoid pasting long logs unless the user asks for them.
 
 Keep run reports brief and information-dense unless the user asks for detail. Prefer one compact run table plus the most important result or first actionable error. Do not paste long logs, raw snapshots, or full notebook outputs by default.