Skip to main content

Connect Other AI Clients to Coginiti

This guide shows you how to connect an AI client that has no dedicated Coginiti guide. Any client that supports the Model Context Protocol (MCP) can use the Coginiti MCP server. The steps depend on what the client supports.

For clients with their own guide, see Claude Desktop, Claude Code, Codex CLI and Codex Desktop.

info

Available in Coginiti Team and Enterprise. Coginiti Pro is not supported yet.

For the full list of tools and limits, see the Coginiti MCP server reference.

Prerequisites​

  • An AI client that supports MCP servers
  • A user account on a Coginiti Team or Enterprise instance
  • The MCP server enabled on that instance (it is on by default, see Administrator settings)
  • Node.js 18 or later, only if the client supports local (stdio) servers and not remote HTTP servers (see Case B)

What Every Client Needs​

Every client needs the same three values:

ValueWhat to use
Endpoint URLYour instance address followed by /api/v1/mcp, for example https://coginiti.example.com/api/v1/mcp
AuthenticationThe header Authorization: Bearer <your-api-key>
TransportStreamable HTTP

Different clients name these fields differently. Look for terms such as "remote server", "HTTP server", "URL" and "headers" in the client's documentation.

Solution​

Step 1: Create an API Key​

  1. Sign in to Coginiti.
  2. Click the Settings icon in the lower-left corner.
  3. Administrators only: click the Personal tab. Other users see their settings without tabs.
  4. Expand Account & Security, then click API Keys.
  5. Click Add New Key.
  6. Enter a Token Name. Optionally, add a Description.
  7. Select an Expiration. The default is No expiration.
  8. Administrators only: in User, select the user the key is created for. The key works with that user's permissions.
  9. Click Save and copy the key. It is shown only once.

Choose a key that does not expire if you can. For more about keys, see the API reference.

Step 2: Test the Endpoint​

Check the endpoint and the key before you change the client. Run this command.

On macOS and Linux:

curl -s -X POST "https://coginiti.example.com/api/v1/mcp" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

On Windows, in PowerShell. curl is an alias for another command there, so this uses Invoke-RestMethod:

Invoke-RestMethod -Method Post -Uri "https://coginiti.example.com/api/v1/mcp" `
-Headers @{ Authorization = "Bearer <your-api-key>"; Accept = "application/json, text/event-stream" } `
-ContentType "application/json" `
-Body '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

A working endpoint returns a JSON result that contains serverInfo. In PowerShell, look for serverInfo under result. For other results, see Troubleshooting.

warning

The command saves the key in your shell history. Remove that entry after you run the command. In PowerShell, (Get-PSReadLineOption).HistorySavePath shows the history file.

If the server uses a self-signed or internal-CA certificate, curl reports a certificate error. For this test only, on a network you trust, add -k to the curl command to skip certificate verification. In PowerShell 7 and later, add -SkipCertificateCheck instead. Do not skip verification in the client. Trust the certificate instead, see Rules for Any Client.

Step 3: Choose How the Client Connects​

Check the client's documentation. Then follow the case that matches.

In a JSON configuration file, add only the coginiti entry to the existing mcpServers section. Do not paste a complete JSON object into a file that already has settings, because that corrupts the file.

Case A: the Client Supports Remote HTTP Servers​

Add a server in the client's MCP configuration. Use the three values from What Every Client Needs.

Most clients use a form like this. The field names vary by client:

{
"mcpServers": {
"coginiti": {
"type": "http",
"url": "https://coginiti.example.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
}
}

If the client can read a header value from an environment variable, use that. It keeps the key out of the file.

Case B: the Client Supports Only Local (stdio) Servers​

Use the mcp-remote bridge. It runs on your machine, speaks stdio to the client, and forwards requests to the Coginiti endpoint. It needs Node.js, see Prerequisites.

Configure the client to start this command:

npx -y mcp-remote https://coginiti.example.com/api/v1/mcp --transport http-only --header "Authorization:${AUTH_HEADER}"

Set the environment variable AUTH_HEADER to Bearer <your-api-key> for that command. Most clients have an env field for this. This keeps the key out of the command line.

If the client does not use your shell PATH, give the full path to npx. Find it with which npx on macOS and Linux, or where npx on Windows. On Windows, write backslashes in command twice in a JSON file, for example C:\\Program Files\\nodejs\\npx.cmd.

The result in a JSON configuration, for clients that use the command, args and env fields:

{
"mcpServers": {
"coginiti": {
"command": "/full/path/to/npx",
"args": [
"-y", "mcp-remote",
"https://coginiti.example.com/api/v1/mcp",
"--transport", "http-only",
"--header", "Authorization:${AUTH_HEADER}"
],
"env": { "AUTH_HEADER": "Bearer <your-api-key>" }
}
}
}

Step 4: Restart the Client and Check the Connection​

  1. Restart the client completely so that it reads the new configuration.
  2. Check that the client lists the coginiti server and its tools, such as list_connections.
  3. Ask: List my Coginiti connections.

The client calls list_connections and shows your connections.

Work with Coginiti in the Client​

Ask in plain language. The client picks the tool.

You askThe client uses
"List my Coginiti connections."list_connections
"On coginiti_retail_demo, show the tables in the mart schema."browse_db
"Run select count(*) from mart.business_unit_dimension on coginiti_retail_demo."execute_sql
"Open @Personal/retail/reports/reports_regular/daily_snapshot and explain what it calculates."get_catalog_asset
"Save that query as @Personal/retail/reports/channel_sales."create_catalog_asset
"Search the workspace for anything about store rankings."search
"From the coginiti_retail_demo_semantic layer, give me gross sales by sales channel."execute_semantic_query

Follow these tips:

  • Name the connection exactly as list_connections shows it.
  • Prefer a semantic layer to raw SQL when one exists. You get its governed definitions.
  • Ask the client to filter, aggregate or add a LIMIT for large tables. See Large Results.
  • Give paths that start with a workspace, such as @Personal or @Shared.
warning

execute_sql does not limit the statement type. A statement that changes data will run. Use a connection whose database user has only the rights you want the client to have.

Rules for Any Client​

  • Keep the key secret. Do not commit a configuration file that contains the key. Prefer environment variables.
  • Use a key that does not expire. An expired or revoked key makes every call fail with an authorization error.
  • Use HTTPS. Plain HTTP works only for http://localhost, unless the client or bridge is told to allow it. Use plain HTTP to another host only on a network you trust.
  • Limit what the client can do. The client acts with the permissions of the key's owner. execute_sql runs any statement type. Use a connection whose database user has only the rights you want the client to have.
  • Trust the certificate. Clients verify the server certificate. For a self-signed or internal-CA certificate, add the CA to the client's trusted certificates. For a Node.js based client or the bridge, set NODE_EXTRA_CA_CERTS to the path of a PEM file. The certificate must name the host in the URL.

Troubleshooting​

The Client Returns a 401 Error​

The API key is missing, revoked or expired. It also stops working while its owner is disabled, and works again when the owner is enabled. Create a new key. Update the Authorization header, and run the test command again to check the new key.

The Client Returns a 403 Error​

Sign in to the Coginiti web UI once. Change your password if you are asked to.

The Client Returns a 404 Error or "Not Found"​

  • Check that the URL ends with /api/v1/mcp.
  • Ask an administrator to check that Enable MCP server is on in Settings > MCP Server. When it is off, the endpoint returns "Not found".

The Client Returns "The Connection Attempt Failed" or "The Connection Timed Out"​

The MCP server works, but Coginiti cannot reach the database of that connection. Tools that do not use the database, such as list_connections, still work. Open the connection in the Coginiti web UI and test it. If it fails there too, ask your database administrator to check that the database is running and reachable from the Coginiti server.

The Client Returns a Certificate Error​

You may see self-signed certificate or UNABLE_TO_VERIFY_LEAF_SIGNATURE. The server uses a certificate that your machine does not trust. Ask your administrator for a certificate from a trusted CA, or follow the certificate steps in this guide.

"The Input Has N Statements, but Only One Statement Can Run per Call"​

The client sent several statements in one call. Ask it to send them one at a time.

A Result Is Incomplete​

Look for truncated: true in the result. Ask the client to narrow the query. See Large Results.

An Update or Delete Fails Because the Item Changed​

Someone edited the item after the client read it. Ask the client to read the item again and retry.

The Web UI Shows "Concurrency Violation: Stale Data Detected"​

The client edited an item that is open in your browser. Click Reload on the message to load the changed item. Unsaved edits in that tab are discarded.

The Web UI Shows "Concurrency Violation: Some of Entities Are Under Editing"​

Two saves overlapped. Nothing is stale. Save again after a moment.

The Coginiti Address Changed​

Update the URL in the client configuration. The API key belongs to one instance. Create a new key on the new instance and update the Authorization header too.

The Test Works, but the Client Shows No Tools​

  • Check that the client supports Streamable HTTP, or use Case B.
  • Check that the header is spelled Authorization and the value starts with Bearer followed by the key.
  • Restart the client completely.
  • Read the client's MCP log for the reason.

spawn npx ENOENT in the Log​

Use the full path to npx in the configuration.

"Non-HTTPS URLs Are Only Allowed for Localhost"​

The bridge refuses plain HTTP to another host. Use HTTPS, or add --allow-http to the bridge arguments on a trusted network.


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

For the full list of tools and limits, see the Coginiti MCP Server Reference.


tip

For more information about other exciting Coginiti features visit our documentation

Thank you for choosing us!​