Skip to content
Optima docs
AI assistants (MCP)

Connect an assistant

Connect Claude, ChatGPT, Claude Code, Cursor or another MCP client to Optima with a dedicated API key.

Connecting takes two things: the MCP server address of your instance and an API key made for the assistant. Chat assistants (Claude, ChatGPT) sign in through a page on your Optima server where you paste the key; developer tools (Claude Code, Cursor) send the key with every request.

Before you start

  • The server address. Open Settings → Access → API keys, tab Connected AI apps. The MCP server address at the top is what you give the assistant; it ends in /mcp. If it is not shown, ask your Optima operator.
  • A key of its own. Create one key per assistant and job under API keys, with only the roles it needs. Never reuse an integration key, and never use a key that can reach several environments: the sign-in page refuses it. Which roles to give is on Permissions and privacy.
  • Creating keys needs the api_key_manager role, or another role your administrator has given access to this area — see Licences and roles.

Claude

  1. In Claude, open Settings → Connectors and choose Add custom connector.
  2. Name it, for example "Optima", enter the MCP server address and select Connect.
  3. A page served by your Optima server opens. Before you paste anything, check that the address bar shows your Optima server and that the page says it redirects to claude.ai or claude.com.
  4. Paste the API key and continue. Claude returns to the chat and the connector lists the tools the key allows.

Claude never sees the key. It gets a short-lived access token that renews itself while the connector is in use, and the connection appears on the Connected AI apps tab, where it can be revoked.

ChatGPT

  1. In ChatGPT's connector settings, turn on Developer mode. Where this setting lives changes between ChatGPT releases.
  2. Create a connector with the MCP server address and choose OAuth as the authentication.
  3. ChatGPT opens the same sign-in page. Check that the address is your Optima server and that the redirect is to chatgpt.com, then paste the key.

Claude Code, Cursor and other developer tools

Tools that can send a request header connect with the key directly, with no sign-in page. Claude Code:

claude mcp add --transport http optima https://mcp.example.com/mcp \
  --header "Authorization: Bearer <your-optima-api-key>"

Cursor, in .cursor/mcp.json:

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

Replace the address with your MCP server address. Any other MCP client that supports the streamable HTTP transport and custom headers works the same way; the header X-APIKey: <your-optima-api-key> is accepted too.

A key sent this way creates no row on the Connected AI apps tab: the key itself is what you control. To cut off such a tool, disable, rotate or delete the key. Keep the key out of shared repositories; .cursor/mcp.json in particular is often committed.

Check that it worked

  1. Ask something the key's roles cover, such as "Describe the data model" or "Which campaigns ran last month?"
  2. For Claude and ChatGPT, the connection shows as Active on the Connected AI apps tab, with the client, the key and when it was last used.
  3. Open Settings → Workspace → Privacy, tab Audit log. Reads of personal data the assistant made show the key as the Actor; for a chat connection the entry says "via AI connection".

Take access away

  • One chat connection: Revoke it on the Connected AI apps tab. It stops working within seconds and the assistant has to connect again.
  • Everything the key reaches: disable the key (reversible), or delete it. Rotating also works, but the old key keeps working until the rotation grace period ends.
  • Revoking a connection does not stop someone who holds the key from connecting again. If the key may have been shared, rotate or delete it.

On this page