Skip to main content

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.

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.

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​

  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.

api_key_creating_claude_code.gif

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:

ScopeStored inAvailable to
local (default)~/.claude.json, for the current projectYou, in this project
user~/.claude.jsonYou, in all projects
project.mcp.json in the project rootEveryone who clones the repository

On Windows, ~/.claude.json is %USERPROFILE%\.claude.json.

warning

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>"
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.

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​

  1. Run claude mcp list. The coginiti server must show Connected.
  2. Start claude and run /mcp. It lists the server and its tools.
  3. Ask: List my Coginiti connections.

Claude calls list_connections and shows your connections.

claude_code_connection_check.gif

Work with Coginiti in Claude Code​

Ask in plain language. Claude picks the tool.

You askClaude 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 Claude 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 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.


tip

For more information about other exciting Coginiti features visit our documentation

Thank you for choosing us!​