Skip to main content

Coginiti MCP Server Reference

The Coginiti MCP server lets AI clients work with your connections, catalog and semantic layers through the Model Context Protocol (MCP). It runs inside Coginiti and exposes 16 tools over a single HTTP endpoint.

Overview​

PropertyValue
Endpoint/api/v1/mcp
TransportStreamable HTTP
AuthenticationCoginiti API key, sent as Authorization: Bearer <key>
EditionsTeam, Enterprise
Default stateEnabled
info

Coginiti Pro is not supported yet.

Every tool runs with the permissions of the API key's owner. Catalog edits follow that user's catalog permissions.

Authentication​

Requests must carry a valid Coginiti API key in the Authorization header. To create a key, see the API reference.

Authorization: Bearer <your-api-key>

Key behavior:

  • A key works until it expires or is deleted.
  • Disabling a user suspends their API keys. While the user is disabled, the keys are rejected with 401.
  • When the user is enabled again, the same keys work again.
warning

Disabling a user does not revoke their API keys. To end a user's access to MCP for good, delete their API keys as well as disabling the user.

Tools​

The server provides 16 tools in four groups.

Connections and Databases​

ToolDescription
list_connectionsList the database connections available to you.
browse_dbBrowse a connection's databases, schemas, tables and columns, one level at a time.
execute_sqlRun one SQL statement against a connection.
execute_scriptRun a saved catalog script, or one block of it, against a connection.

Catalog​

ToolDescription
list_catalogList catalog items at a path, or the Project Hub packages.
get_catalog_assetGet an asset's content, metadata and revision.
create_catalog_folderCreate a folder or project.
create_catalog_assetCreate a SQL or CoginitiScript asset.
update_catalog_folderRename a folder.
update_catalog_assetRename an asset or replace its content.
delete_catalog_folderDelete an empty folder.
delete_catalog_assetDelete an asset.
ToolDescription
searchSearch the catalog, query history and database objects.

Semantic Layers​

ToolDescription
list_semantic_layersList the semantic layers you can access.
get_semantic_layer_metadataGet the entities, dimensions and measures of a layer.
execute_semantic_queryRun a semantic-layer query.

Tool Access Levels​

Each tool declares what it does to Coginiti-managed state. Clients see this as MCP annotations.

LevelToolsMeaning
Read onlylist_connections, browse_db, list_catalog, get_catalog_asset, search and the three semantic layer toolsNever changes anything. Clients may call these freely.
Readexecute_sql, execute_scriptRuns your work against a connection. That work can change your databases, so clients are not told it is read only.
Writecreate_*, update_* and delete_* catalog toolsCreates, changes or deletes catalog items.

Tool Behavior​

SQL and Scripts​

Rules:

  • execute_sql runs one statement per call. Input with several statements is rejected and nothing runs.
  • execute_script runs one statement per call. A script with several top-level statements is rejected and nothing runs. To run part of a script, pass block.
  • On PostgreSQL, DO $$ ... $$ and CREATE FUNCTION count as several statements. So does Snowflake EXECUTE IMMEDIATE $$ ... $$. They cannot run through execute_sql yet.
  • The params argument fills $name parameters by plain text substitution. Values are not bound.
  • A script that has only named blocks has no default block. Pass block with the block name. Only public blocks (names that start with a capital letter) can run.
  • block_args gives values for the declared parameters of the block, by parameter name. Every declared parameter needs a value. It works only with block.
  • project_version selects the version of a Project Hub package. It works only on @Project Hub paths.
  • execute_script accepts scripts only. It refuses project files, actions, linter.toml, .smdl files and folders.
  • execute_sql does not limit the statement type.
warning

Do not pass untrusted text in params. Values are substituted as plain text, so quote and check them.

Browsing a Database​

browse_db lists one level at a time. Without path, it lists the top level. To go deeper, pass the path of a node from the previous result: database, schema, table, then columns.

If the database cannot be reached, the error names the connection and gives a short reason. It does not show driver details.

Catalog Paths and Revisions​

Catalog paths start with a workspace, such as @Personal or @Shared.

get_catalog_asset and every write return the item's revision. The update and delete tools require the current revision. If the item changed since it was read, the call fails and does not overwrite the change. The client must read the item again before it retries.

get_catalog_asset cuts long content. It returns data.truncated and data.size_bytes.

Project Hub​

Published Project Hub packages are read-only.

Rules:

  • list_catalog on @Project Hub lists the packages with their versions and the latest version.
  • A package path is @Project Hub/<package>. A script in it is @Project Hub/<package>/<script>.
  • The project_version argument selects a version. The default is the latest. It works only on @Project Hub paths.
  • An unknown version returns Project Hub path '...' does not contain version '...'.

Search​

search can look in these sources:

SourceContent
CatalogCatalog items
query_historySQL that ran before
platform_db_objectIndexed database objects

Each hit has a short content snippet. Read the full content with get_catalog_asset. A catalog hit has a catalog_path that the catalog tools accept.

Semantic Queries​

execute_semantic_query returns the same result fields as execute_sql, except it has no stats. A join can omit the ON condition, as in FROM fact AS f JOIN dim AS d. The semantic model supplies the join keys.

Large Results​

Results are cut to protect the client. A cut result is a normal result, not an error.

ToolCut byDefaultMaximum
execute_sql, execute_scriptBytes only (no row limit)1,000,000 bytesSet by an administrator
execute_semantic_queryRows only (no byte limit)1,000 rows10,000 rows

Result fields:

FieldMeaning
returnedThe number of rows in the response.
truncatedtrue when rows were left out.
truncated_bybytes for SQL and scripts, rows for semantic queries. Present only when truncated is true.
totalThe number of rows. Present only when nothing was left out.

When a result is cut, the real row count is not known and total is missing.

Decimals are JSON numbers that keep their scale. A SQL NULL is a JSON null.

The max_rows Argument​

execute_semantic_query accepts max_rows, with a minimum of 1.

Rules:

  • When omitted, the value is the Limit rows number to value in the system query execution settings, capped at the MCP maximum row limit. The default is 1,000.
  • A value above the maximum row limit is rejected with Invalid arguments: 'max_rows': must be at most <N>. It is not silently capped.

Administrator Settings​

Administrators manage the server under Settings > MCP Server. Changes apply to new tool calls after you save them. You do not need to restart the server.

SettingDescriptionDefault
Enable MCP serverTurns the endpoint on or off. When off, requests receive "Not found".On
Max result size (bytes)Byte limit for execute_sql and execute_script results.1,000,000
Maximum row limitLargest max_rows a caller can request.10,000

mcp-server-settings.gif

note

All three are system-wide settings. Users cannot override them in their own preferences.

Error Messages​

MessageCause
401The API key is missing, revoked or expired, or its owner is disabled. A key works again when its owner is enabled.
404 / Not foundThe MCP server is disabled, or the URL is wrong.
403The user must sign in to the web UI once, or change the password if asked.
Invalid arguments: ...A required argument is missing or wrong. The message names the argument.
The input has N statements, but only one statement can run per callMore than one statement was sent to execute_sql.
The script has N statements, but execute_script runs only one per callThe script has several top-level statements and no block was given. Run the statements one at a time with execute_sql, or put them in named blocks and pass block.
The script has only named code blocks, so there is no default block to runexecute_script ran a script with only named blocks and no block argument.
'<path>' is not an executable scriptexecute_script was pointed at a file that is not a script.

Audit and Security Log​

Each tool call writes a McpToolCalled event (Event ID 26) to the security log. SQL that runs through execute_sql, execute_script and execute_semantic_query is also recorded in the query audit with the origin MCP.

For other security events, see the Security Log Reference.


For related guides, see:
Connect Claude Desktop to Coginiti
Connect Claude Code to Coginiti
Connect Codex CLI to Coginiti
Connect Codex Desktop to Coginiti
Connect Other AI Clients to Coginiti


tip

For more information about other exciting Coginiti features visit our documentation

Thank you for choosing us!​