Connect Claude Code to Coginiti
This guide shows you how to connect Claude Code to your Coginiti instance through the Coginiti MCP server. Claude Code connects to the endpoint directly over HTTP. It needs no bridge and no Node.js setup.
To connect the Claude Desktop app, see Connect Claude Desktop to Coginiti. For any other MCP client, see Connect Other AI Clients to Coginiti.
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.
For Claude Code’s MCP setup options and supported authentication methods, see Anthropic’s Claude Code MCP documentation.
Prerequisites
- Claude Code installed
- 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)
Solution
Step 1: Create an API Key
- Sign in to Coginiti.
- Click the Settings icon in the lower-left corner.
- Administrators only: click the Personal tab. Other users see their settings without tabs.
- Expand Account & Security, then click API Keys.
- Click Add New Key.
- Enter a Token Name. Optionally, add a Description.
- Select an Expiration. The default is No expiration.
- Administrators only: in User, select the user the key is created for. The key works with that user's permissions.
- 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: Find Your Endpoint URL
The endpoint is your instance address followed by /api/v1/mcp, for example:
https://coginiti.example.com/api/v1/mcp
Step 3: Add the Server
Choose one of two ways.
Option A: Use the Command Line
Run this command, with your endpoint URL and API key.
On macOS and Linux:
claude mcp add --transport http coginiti \
https://coginiti.example.com/api/v1/mcp \
--header "Authorization: Bearer <your-api-key>"
On Windows, in PowerShell:
claude mcp add --transport http coginiti https://coginiti.example.com/api/v1/mcp --header "Authorization: Bearer <your-api-key>"
Add --scope to choose where Claude Code stores the server:
| Scope | Stored in | Available to |
|---|---|---|
local (default) | ~/.claude.json, for the current project | You, in this project |
user | ~/.claude.json | You, in all projects |
project | .mcp.json in the project root | Everyone who clones the repository |
On Windows, ~/.claude.json is %USERPROFILE%\.claude.json.
With local and user scope, the key is saved in plain text in ~/.claude.json. Do not use project scope with a literal key. It would put the key in a file you commit. Use Option B instead. The command also saves the key in your shell history. Remove that entry after you run the command. In PowerShell, (Get-PSReadLineOption).HistorySavePath shows the history file.
Option B: Use a .mcp.json File
This option keeps the key out of the file. Set the key as an environment variable, then reference it in .mcp.json in your project root:
{
"mcpServers": {
"coginiti": {
"type": "http",
"url": "https://coginiti.example.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer ${COGINITI_API_KEY}"
}
}
}
}
Set the variable in the shell where you start Claude Code.
On macOS and Linux:
export COGINITI_API_KEY=<your-api-key>
On Windows, in PowerShell:
$env:COGINITI_API_KEY = "<your-api-key>"
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.
Claude Code asks you to approve a project server the first time you run claude in the project.
Connect to a Server with a Self-signed Certificate
Claude Code trusts your operating system's certificate store by default. If the CA certificate is not there, point Claude Code at it before you start it.
On macOS and Linux:
export NODE_EXTRA_CA_CERTS=/path/to/ca.pem
claude
On Windows, in PowerShell:
$env:NODE_EXTRA_CA_CERTS = "C:\path\to\ca.pem"
claude
Get the PEM file from your administrator, or export it from your browser. The certificate must name the host in your endpoint URL. If you connect by IP address, it needs an IP address entry.
Step 4: Check the Connection
- Run
claude mcp list. Thecoginitiserver must showConnected. - Start
claudeand run/mcp. It lists the server and its tools. - Ask:
List my Coginiti connections.
Claude calls list_connections and shows your connections.

Work with Coginiti in Claude Code
Ask in plain language. Claude picks the tool.
| You ask | Claude 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_connectionsshows it. - Prefer a semantic layer to raw SQL when one exists. You get its governed definitions.
- Ask Claude to filter, aggregate or add a
LIMITfor large tables. See Large Results. - Give paths that start with a workspace, such as
@Personalor@Shared.
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 Claude to have.
Troubleshooting
Claude Code 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 server with the new key. If you use .mcp.json, check that COGINITI_API_KEY is set in the shell where you started Claude Code.
Claude Code Returns a 403 Error
Sign in to the Coginiti web UI once. Change your password if you are asked to.
Claude Code 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".
Claude Code 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.
Claude Code 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"
Claude Code 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 Claude Code to narrow the query. See Large Results.
An Update or Delete Fails Because the Item Changed
Someone edited the item after Claude Code read it. Ask Claude Code to read the item again and retry.
The Web UI Shows "Concurrency Violation: Stale Data Detected"
Claude Code 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
Create a new key on the new instance. The API key belongs to one instance. Run claude mcp remove coginiti, then add the server again with the new URL and key. If you use .mcp.json, change the URL there and update COGINITI_API_KEY.
claude mcp list Shows "Failed to Connect"
The line ends with the reason, such as an HTTP status code. Find the matching entry above.
claude mcp list Warns About a Missing Variable
The ${COGINITI_API_KEY} variable is not set in the shell where you started Claude Code. Export it and start Claude Code again.
"Pending Approval"
Run claude in the project and approve the coginiti server from .mcp.json.
For related guides, see:
Connect Claude Desktop to Coginiti
Connect Codex CLI to Coginiti
Connect Codex Desktop to Coginiti
Connect Other AI Clients to Coginiti
For the full list of tools and limits, see the Coginiti MCP Server Reference.
For more information about other exciting Coginiti features visit our documentation