MCP

Connect an MCP client to Querio to work with workspace data and author notebooks directly. For your first notebook, follow Get started with MCP.

This interface lets your client coordinate notebook work. It is separate from Querio's in-app conversational agent.

Endpoint and authorization

Use a Streamable HTTP MCP client with this server URL:

https://app.querio.ai/mcp

For another Querio deployment, use /mcp on that app's origin. The endpoint is part of the webapp; there is no separate MCP server address.

Requests require an Authorization: Bearer ... header. Browser cookies do not authenticate MCP calls. On a 401 response, the WWW-Authenticate header points to protected-resource metadata at /.well-known/oauth-protected-resource/mcp. Your client should follow its browser OAuth flow; public clients use authorization code with PKCE and explicit connection approval. When allowed, offline_access enables refresh tokens, not additional Querio permissions.

Client registration depends on the deployment. If your client cannot register or finish authentication, contact Querio instead of using an app session cookie. MCP uses your existing Querio access; approving a client does not grant workspace or datasource permissions. See Users, roles and groups.

Discovery and bundled resources

After initialize, the client can use tools/list to get names, input schemas and annotations, and tools/call to invoke a listed tool. Use resources/list and resources/read for the two bundled Markdown guides:

Read both before authoring a notebook. They are MCP resources, not tools or CLI commands. A workspace file path returned by a tool is not an MCP resource you can read.

Workspace arguments

Use me_get and workspaces_list to identify your workspace. Every workspace-scoped tool call needs a nonempty, top-level workspaceId; the endpoint does not remember a selection. Only me_get, workspaces_list and workspaces_create omit it. A token restricted to one workspace cannot access another by changing the ID.

For example, pass these parameters to tools/call to read a saved notebook:

{
  "name": "notebooks_get",
  "arguments": {
    "workspaceId": "WORKSPACE_ID",
    "id": "NOTEBOOK_ID"
  }
}

Discovery shows the tools the endpoint serves, not what your identity can use. Seeing a datasource does not establish query access.

Supported tool lookup

The endpoint serves 27 tools. Every tool below requires workspaceId except the three under Identity and workspaces. Arguments are top-level unless prefixed with body.. Use tools/list for full input schemas, including optional fields.

Identity and workspaces

workspaces_create also accepts body.fileMode, body.git and body.context. See Files and versions.

Datasources

Give the datasources_setup URL to the user. Credentials go in that browser form, never in tool arguments or an agent conversation. Wait for the user to confirm setup before inspecting or introspecting. Prefer explicit schema or table targets for introspection; refresh updates already-catalogued tables rather than discovering new ones. The result contains a catalog path, not a background job. Connection and query-access steps belong in Connect a datasource.

Saved notebooks

Read before updating, and reconcile a timestamp conflict before trying again. See Notebooks, cells and outputs.

Environments and sessions

Each environment hosts one active notebook session. Explicit CLI/API opens allow one active explicit session per saved notebook; browser View uses independent runtimes. Use separate environments for concurrent notebooks, and keep workspace, notebook, environment and session IDs distinct. See Execution and sessions.

Code and working changes

Check session readiness before code_exec. This scratchpad calculation in an existing ready session illustrates its arguments:

{
  "name": "code_exec",
  "arguments": {
    "workspaceId": "WORKSPACE_ID",
    "querio_session_id": "SESSION_ID",
    "body": { "code": "print(6 * 7)" }
  }
}

A successful call prints 42, but does not create a durable notebook cell. Follow querio://guides/notebook-authoring to author one. changes_status and changes_diff require an open session with a separate working copy (changeset file mode). Use changes_publish to publish reviewed changes or open a GitHub pull request, as described below. A Querio working-copy ID is not a Git branch name. Status and diff remain available after an idle runtime unloads. Match a submitted execution's runId to an item's id from sessions_list_executions and check that same ID until it reaches a terminal status.

Publish or discard working changes

Read status, pause writers and review the diff before publishing. Without GitHub, paths does not limit publication to those files. A stale canonical version is rejected; inspect the outcome before a deliberate retry. An opened pull request is not a merged publication. Discard does not undo published files or saved notebook edits.

Copy selected files

For a new text file, supply create: "true", overwrite: "false" and body: {"encoding":"utf8","content":"file text"}. Binary content uses encoding: "base64" with canonical padded base64. Both the JSON request and decoded file are limited to 100 MiB. Do not copy credentials. Write flags and revision headers are mutually exclusive; see write intent. These tools do not read files from your computer: your client must supply their contents.

Results, errors and cleanup

Results use text content. JSON API responses are encoded inside a text block; do not rely on structuredContent. Check both isError and the response body. A non-2xx API response sets isError: true, but an HTTP 200 body can still report success: false, execution errors or a failed status. A successful submission does not prove that cells ran or saved. Inspect the intended cells' current outputs and errors; Execution and sessions explains the lifecycle.

Editable code_exec waits for the notebook save, and sessions_close saves when closing. There is no separate MCP save tool. Close only sessions you created or were asked to close, then close their environments. If closing fails, inspect the error before proceeding. Saved notebooks remain available after successful cleanup.

Do not automatically retry mutations. A timeout or cancellation does not undo completed writes; a legacy stateless client can stop waiting while execution continues. Inspect current state first.

Capability limits

• MCP exposes no file listing, reading, recursive upload or download tools. Use files_write for selected file contents and the CLI reference for directory uploads and downloads.
• The two resources are bundled authoring guidance, not a workspace filesystem or docs search.
• This tool list has no code_skill, runs_get, runs_cancel or workspace_show. Use sessions_list_executions for the exposed execution records.
• This endpoint has no conversational QA renderer, general API-request tool, datasource credential submission tool or agent-session management tool. For work with Querio's in-app agent, see Get started in the app.

Use the discovered schemas for this endpoint. CLI flags and CLI workspace selection are not MCP arguments.