Skip to main content

Connect Codex Desktop to Coginiti

This guide shows you how to connect the Codex desktop app to your Coginiti instance through the Coginiti MCP server. You add the server in the app settings. The app connects to the endpoint directly over HTTP. It needs no bridge.

To connect Codex CLI, see Connect Codex CLI 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 Codex’s MCP setup options and supported authentication methods, see OpenAI’s MCP documentation.

Prerequisites​

  • The Codex desktop app 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_codex_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 in the app settings.

  1. Open Settings > Integrations > Plugins.

  2. Click Add, then click Add MCP server.

  3. In Name, enter coginiti.

  4. Set Type to Streamable HTTP.

  5. Fill in the fields:

    FieldValue
    URLThe endpoint URL from Step 2
    HeadersAdd a header with key Authorization and value Bearer <your-api-key>

    Replace <your-api-key> with the key you copied in Step 1. Include the word Bearer followed by a space before the key.

  6. Leave Bearer token env var and Headers from environment variables empty.

  7. Click Save. The key is stored in the app settings.

Connect to a Server with a Self-signed Certificate​

The app must trust the certificate of your server. Ask your administrator for a certificate from a trusted CA, or add the CA certificate to your operating system's trusted certificates. The certificate must name the host in your endpoint URL.

Step 4: Check the Connection​

  1. Open Settings > Integrations > Plugins. The coginiti server must appear in the MCPs tab.
  2. Start a new chat.
  3. Ask: List my Coginiti connections.

The app calls list_connections and shows your connections.

note

If the Authorization header is missing or the key is invalid, Coginiti returns a 401 error.

codex_desktop_connection_check.gif

Work with Coginiti in the App​

Ask in plain language. The app picks the tool.

You askThe app 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 app 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 app to have.

Troubleshooting​

The App 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. Check that the Authorization header is present and its value starts with Bearer followed by the API key. Save the server settings, then retry.

The App Returns a 403 Error​

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

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

An Update or Delete Fails Because the Item Changed​

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

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

The app 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 server settings. The API key belongs to one instance. Create a new key on the new instance and update the Authorization header too.

The Server Shows No Tools​

Check that Type is Streamable HTTP, not STDIO. Quit the app completely and open it again.


For related guides, see:
Connect Claude Desktop to Coginiti
Connect Claude Code to Coginiti
Connect Codex CLI 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!​