Skip to main content

Connect Claude Desktop to Coginiti

This guide shows you how to connect Claude Desktop to your Coginiti instance through the Coginiti MCP server. You add the server to the Claude Desktop configuration file. After you connect, Claude can list your connections, run SQL, work with the catalog and query semantic layers on your behalf.

To connect the Claude Code command line tool, see Connect Claude Code 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 Desktop’s MCP setup options, see Anthropic’s custom connectors documentation and Connect to local MCP servers.

Prerequisites​

  • Claude Desktop installed on macOS or Windows
  • 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. The Claude Desktop configuration file supports only local MCP servers, so the setup uses the mcp-remote bridge. The bridge runs on your computer and reaches Coginiti from your network. Custom connectors in Claude Desktop connect from Anthropic’s cloud, so they work only with servers that are open to the public internet

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_desktop.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​

You add the server to the Claude Desktop configuration file. The mcp-remote bridge forwards its traffic to the Coginiti endpoint and adds your API key as an Authorization: Bearer header.

  1. Find the full path of npx:

    SystemCommand
    macOSwhich npx
    Windowswhere npx

    Claude Desktop does not use your shell PATH, so the configuration needs the full path, for example /opt/homebrew/bin/npx on macOS or C:\Program Files\nodejs\npx.cmd on Windows. If you use fnm or nvm, use a stable path, not the per-shell path that which prints.

  2. Open the Claude Desktop configuration file:

    SystemLocation
    macOS~/Library/Application Support/Claude/claude_desktop_config.json
    Windows%APPDATA%\Claude\claude_desktop_config.json
  3. Add a coginiti entry under mcpServers. The file already starts with { and holds other settings. Do not paste a complete JSON object into it, because that corrupts the file. Instead, replace the first { in the file with this block. Keep the comma at the end, because the settings that were already in the file follow it:

    {
    "mcpServers": {
    "coginiti": {
    "command": "/opt/homebrew/bin/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>" }
    }
    },

    If the file already has an mcpServers section, add only the coginiti entry inside it. If the file contains only {}, remove the comma after the mcpServers section and add } on a new line at the end.

    Replace command, the URL and <your-api-key> with your values. The key goes in env, so it does not appear on the command line.

    On Windows, write backslashes in command twice, because the file is JSON:

    "command": "C:\\Program Files\\nodejs\\npx.cmd",
  4. Quit Claude Desktop completely and open it again. On macOS, press Cmd+Q. On Windows, right-click the Claude icon in the system tray and click Quit. Closing the window is not enough.

warning

The configuration file now contains your API key. Treat the file like a password. Do not share it or commit it to source control.

Connect to a Server with a Self-signed Certificate​

mcp-remote verifies the server certificate. If your server uses a self-signed or internal-CA certificate:

  1. Get a PEM file with the CA certificate from your administrator, or export it from your browser. For a self-signed server, use the server certificate itself.

  2. Add its path to env in the configuration, then quit and reopen Claude Desktop:

    "env": {
    "AUTH_HEADER": "Bearer <your-api-key>",
    "NODE_EXTRA_CA_CERTS": "/path/to/ca.pem"
    }

The certificate must name the host in your endpoint URL. If you connect by IP address, the certificate needs an IP address entry.

Connect Over Plain HTTP​

http://localhost works as is. For plain HTTP to another host, add "--allow-http" to args. Use this only on a network you trust. Quit and reopen Claude Desktop after you change the configuration.

Step 4: Check the Connection​

  1. Start a new chat.
  2. Open the connectors menu and check that coginiti lists tools such as list_connections.
  3. Ask: List my Coginiti connections.

Claude calls list_connections and shows your connections.

claude_desktop_connection_check.gif

Work with Coginiti in Claude​

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 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 AUTH_HEADER in the configuration.

Claude Returns a 403 Error​

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

Claude 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 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 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 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 to narrow the query. See Large Results.

An Update or Delete Fails Because the Item Changed​

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

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

Claude 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 coginiti entry. The API key belongs to one instance. Create a new key on the new instance and update AUTH_HEADER too.

The Server Shows No Tools or Does Not Start​

  • If the log shows spawn npx ENOENT, use the full npx path in command.
  • Check that node 18 or later is installed.
  • Check that the connector is enabled in the current chat.

The Claude Desktop bridge log is ~/Library/Logs/Claude/mcp-server-<name>.log on macOS and %APPDATA%\Claude\logs\ on Windows.

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

Add "--allow-http" to args, or use an HTTPS URL.

Claude Shows an Old Tool List or Old Tool Descriptions​

A chat that was open while Coginiti was updated can keep the old tool list, even after you restart Claude Desktop. Start a new chat. If the list is still old, remove the coginiti entry, add it again, and restart Claude Desktop.

Configuration Changes Have No Effect​

Quit Claude Desktop completely and open it again. On macOS, press Cmd+Q. On Windows, right-click the Claude icon in the system tray and click Quit. Closing the window is not enough.


For related guides, see:
Connect Claude Code 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!​