MCP clients Beta

Codatum provides an MCP (Model Context Protocol) server. By connecting MCP clients such as Claude and Cursor, you can run the AI agent, work with data and notebooks, and use external services configured under Agent connectors.

INFO

This feature is in beta. The specification might change without notice.

AI agent runs use the permissions of the connected user.

From global nav > Workspace settings > MCP clients, you can configure MCP clients and manage connections.

Connecting

1. In Workspace settings > MCP clients, select Connect client.
2. For Cursor, select Add to Cursor. For Claude Code, copy and run the displayed command. For other clients, copy and configure the displayed MCP URL. The displayed configuration is specific to the current workspace.
3. The MCP client opens the Codatum authorization page in your browser. Sign in and confirm the destination Workspace.
4. Select scopes under Permissions, and then select Authorize.

After approval, the connection appears in the connection list.

A connection is created for each combination of user and workspace. To connect another workspace, repeat steps 1–4 in the destination workspace.

Authorization uses OAuth (authorization code flow with PKCE). No client pre-registration is required; Dynamic Client Registration and Client ID Metadata Documents are supported.

Scopes

Scopes define the operations the connected MCP client can perform. You can select available scopes on the authorization page, and only the approved scopes are granted to the connection. If the MCP client specifies scopes, you can select from the requested scopes.

The MCP client dynamically discovers tool names, descriptions, and input and output definitions based on the approved scopes and the signed-in user's Codatum permissions.

AI agent

The AI agent scope runs agent sessions with an AI Profile. AI Profile restrictions and Codatum Agent tool approval settings apply.

Scope	Description
agent:execute	Create and run AI agent sessions in the connected workspace and read their results.

When an agent action is pending approval (for example, an operation with Auto-approve Tool Execution turned off in Settings), you can approve or reject it from the MCP client. You can also open the session in Codatum.

Analysis and notebooks

Analysis and notebook scopes run catalog, notebook, SQL, and saved query operations directly from the MCP client. Direct calls don't select an AI Profile, so AI Profile-specific restrictions for connections, the current notebook, and tool approvals don't apply. OAuth scopes and Codatum permissions continue to apply.

When you select or request an analysis or notebook scope, Codatum automatically adds support:read so the client can read the file formats required for analysis.

Scope	Description
catalog:read	Search and read connections, schemas, tables, tags, and table annotations in the connected workspace.
catalog:write	Create and update tags and table annotations in the data catalog.
catalog:delete	Delete tags from the data catalog.
notebook:read	Search and read folders, notebooks, and notebook contents in the connected workspace.
notebook:write	Create, edit, move, copy, and rename folders and notebooks. Operations that use a previously read content hash also require notebook:read.
notebook:delete	Delete folders and their contents or delete notebooks.
sql:execute	Validate and execute SQL against connected data sources and read query results. Operations that resolve notebook bindings also require notebook:read.
saved-query:read	Search and read saved queries.
saved-query:write	Create and update saved queries.
support:read	Read Codatum file format references. Added automatically when you select or request another analysis or notebook scope.

Direct tool calls, including delete operations, don't use Codatum Agent approval settings. SQL that exceeds the configured maximum scan size isn't executed.

Agent connectors

Agent connector scopes use Codatum as a gateway to discover and run operations in external services registered under Agent connectors. The target service must have valid credentials. AI Profile restrictions for agent connectors and Codatum Agent tool approval settings don't apply.

Scope	Description
connector:read	Search and read available operations, input and output definitions, and usage instructions for connected services with valid credentials.
connector:execute	Run external service operations and API requests with connected credentials.

External service operations with connector:execute run under the approved OAuth scope without entering Codatum Agent's approval flow.

Direct tool calls wait up to 50 seconds for completion. Continuing an operation beyond 50 seconds isn't supported. Check the target state before retrying a timed-out write operation. See Limits.

Connection list

Each user can view their own connections. Switching to All connections can be performed by a Workspace Owner (Workspace permissions).

Column	Description
Client	The name of the connected MCP client
Connected by	The user who made the connection (shown only in All connections)
Scopes	The operations the connection is allowed to perform (Scopes)
Connected	When the authorization was approved
Last used	When the connection was last used

Disconnecting

Select Disconnect to revoke the authorization. The client can no longer access the workspace and must be authorized again to reconnect. You can disconnect your own connections. A Workspace Owner can disconnect any connection in the workspace.