Appearance
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 manage connections. A Workspace Owner can switch between Client connections and Access profiles.
Use Access profiles to decide who can connect and the maximum permissions they can use.
MCP access profiles
An MCP access profile defines which users and groups can use MCP, the OAuth scopes they can approve, and the Agent connectors they can call directly. A Workspace Owner creates, edits, and deletes profiles under MCP clients > Access profiles. To delete a profile, clear Enable this profile, disconnect every MCP connection that uses the profile, and then select Delete from the profile action menu. You can't undo deletion.
You can assign up to 100 users and groups in total to one MCP access profile. For details, see Limits.
MCP management and usage permissions are separate. A Workspace Owner can't connect unless an enabled MCP access profile is assigned to them.
Disabling a profile or changing its users, scopes, or connector access affects existing connections. Adding a scope to a profile doesn't expand the scopes previously approved for an existing connection.
Connecting
Before connecting, a Workspace Owner must create at least one enabled MCP access profile and make it available to the connecting user.
If no access profile is enabled, the page shows An enabled access profile is required to connect an MCP client. A Workspace Owner does one of the following on Access profiles:
- If there are no profiles, select Create access profile.
- If every existing profile is disabled, select a row, turn on Enable this profile, and then select Save, or select New access profile.
- Open global nav > Workspace settings > MCP clients, and then select Connect client.
- 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.
- The MCP client opens the Codatum authorization page in your browser. Sign in and confirm the destination Workspace.
- Confirm the assigned MCP access profile. If multiple profiles are available, select one.
- Select scopes under Permissions, and then select Authorize.
After approval, the connection appears in the connection list.
Codatum creates a connection for each approved authorization and records the selected MCP access profile. To connect another workspace, repeat steps 1–5 in the destination workspace. If no profile is available, ask a Workspace Owner to assign one.
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. The authorization page shows only scopes allowed by the selected MCP access profile. The effective scopes are the intersection of the scopes approved for the connection and the scopes currently allowed by the profile.
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.
search_catalog_tables and search_saved_queries return all columns by default when called from an MCP client. Set include_columns: false to receive matching columns or a preview of the column list. column_count is the total column count, and columns_truncated indicates that additional matching columns were omitted. Set include_columns: true when you need all columns.
In search results, matched contains highlight excerpts and returned is the number of items in the current page. When has_next is true, pass next_offset as the next call's offset.
run_sql returns up to 50 rows by default. Set limit to retrieve up to the retrieval limit of 1,000 rows.
get_query_result reads an existing query result. Set offset to skip rows from the start and limit to choose how many rows to retrieve. For rows beyond the retrieval limit, use run_sql with SQL OFFSET or a filter.
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. Connector access from the MCP access profile applies. AI Profile restrictions for agent connectors and Codatum Agent tool approval settings don't apply.
| Scope | Description |
|---|---|
connector:execute | Search and read available operations, input and output definitions, and usage instructions for connected services with valid credentials, and run their operations and API requests. |
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
On MCP clients, you can view My connections. Switching to All connections can be performed by a Workspace Owner (Workspace permissions). For a Workspace Owner, the connection list is on Client connections.
| Column | Description |
|---|---|
| Client | The name of the connected MCP client |
| Connected by | The user who made the connection (shown only in All connections) |
| Access profile | The MCP access profile applied to the connection. Shows Deleted profile when the profile no longer exists. |
| Scopes | The operations the connection is allowed to perform (Scopes) |
| Connected | When the authorization was approved |
| Last used | When the connection was last used |
Workspace Owners can filter All connections by MCP access profile.
Disconnecting
Select Disconnect from the row menu 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.