MCP

The MCP endpoint is <app origin>/mcp, on the same origin as your Querio webapp. Connect a Streamable HTTP MCP client to that URL and complete browser authentication. No separate MCP service is required.

Authentication

Registered public clients use authorization-code OAuth with PKCE and explicit connection approval. Creating an account takes you through email verification and back to OAuth without another password entry. Signup does not create a workspace.

The signed-in user's existing permissions govern every API operation. offline_access requests refresh tokens, not additional permissions. The server does not maintain a shared selected workspace: supply workspaceId on each workspace-scoped tool call.

For operators, public client registration remains opt-in. Configure the existing Auth service with UserOAuth__RegistrationEnabled=true and include <app origin>/mcp in UserOAuth__Resources. The webapp uses its existing app URL, public Auth URL, and authentication configuration. Adding the endpoint does not itself enable registration in an existing deployment.

Onboarding

1. Use me_get and workspaces_list to inspect your account and available workspaces.
2. If needed, use workspaces_create with a name and request ID. It provisions a Classic workspace. Save the returned workspace ID and reuse the same request ID if an interrupted creation needs a deliberate retry.
3. Use datasources_setup with the workspace ID and a new datasource slug. The tool returns a browser link immediately.
4. Complete the connection form in the browser. It tests the connection before saving. Never paste datasource credentials into the conversation or tool arguments.
5. Tell the agent when setup is complete. It can then use datasources_get to check metadata and datasources_introspect to populate the catalog. Setup is not polled automatically.

datasources_schema returns the connection JSON Schema, not database tables. Use datasources_schemas and datasources_tables for live discovery.

Files and notebooks

Read code_skill, then its notebook-authoring reference. These are the same bundled guides as querio code skill; use the corresponding MCP tools for their CLI examples.

Use files_mkdir and files_write to upload deliberately selected context files. The MCP server cannot browse your computer or recursively upload a local directory. File content can be UTF-8 text or canonical padded base64. Writes create missing files but do not overwrite existing files unless query.overwrite is explicitly "true". Parent directories must already exist. API containment and file-size limits still apply.

For notebook work:

1. Create or read a saved notebook.
2. Create an execution environment and open a notebook session. Inspect session readiness before executing code. An environment supports one active notebook session at a time.
3. Author cells through code_exec. For whole-notebook execution, use sessions_execute with a run-all event and inspect runs_get until terminal.
4. After successful persistence, explicitly close the session and then its environment. Saved notebooks remain available.

Use changes_status and changes_diff with a session ID to inspect a changeset-backed session. The tools do not add changeset creation or management capabilities.

Failures and safety

HTTP errors and application responses with success: false are tool errors. Reading a failed or cancelled run also returns a tool error with its result. A successful HTTP response alone does not mean execution succeeded.

Mutations are never retried automatically. A timeout or cancellation cannot undo completed or in-flight writes. Legacy stateless clients may stop waiting while the server continues executing. Use runs_cancel for an explicit run cancellation request, then inspect its status. Inspect the existing resource before deciding whether to retry. If notebook saving fails after execution, keep the live session open and resolve persistence instead of replaying code. Session inspection can restore a saved session's runtime, so it is not marked as a side-effect-free read.

The MCP surface is constrained to CLI-supported capabilities. It does not expose raw datasource credentials, arbitrary API requests, agent-session management, permission-response events, caller-chosen run IDs, or file revision headers.