Skip to main content
The Klarity MCP supports two authentication methods. Most clients will use one or the other based on what they support.
MethodWhen to use
OAuthPreferred. Use in any client that supports MCP OAuth (Claude, ChatGPT, Claude Code via the plugin, Codex via codex mcp login, Cursor via the Connect button, Gemini CLI via /mcp auth).
API keyUse when you need a long-lived headless connection, or for custom and automated setups where the OAuth flow isn’t a fit.
Both methods scope the assistant to your active Klarity workspace and obey the same permissions as your Klarity user account.

​
Enable the MCP in your workspace

Whichever auth method your client uses, the very first step is to turn the MCP on for the workspace you want to expose. Sign-in and Bearer-token connections will both fail until this is done.
1

Log in to Klarity

Sign in to your Klarity workspace in a browser.
2

Open MCP settings

Go to Settings → MCP.
3

Pick the workspace to expose

Select the workspace you want your assistant to read from. This is the workspace the MCP will be enabled for.
4

Complete the workspace setup

Follow the in-app prompts to finish enabling the MCP. Once that’s done, return to your AI client and continue with the install steps for it.
If you try to sign in (OAuth) or send a Bearer token before completing the workspace setup, the request will fail. This is the most common cause of “auth failed” errors.
See FAQ for other common install issues.

​
OAuth

When the client supports MCP OAuth, you don’t handle any credentials yourself. The first time the assistant calls a Klarity tool, the client redirects you to sign in to Klarity. After that, the client manages the token. Per-client setup is covered in the Install pages.
Your organization may need to approve the Klarity connector or app before users can sign in. Contact your Klarity workspace admin if the OAuth redirect fails.

​
API key

API key auth uses a long-lived secret that you generate in Klarity and pass to the MCP server as a Bearer token. Use this for any custom or headless setup, or when a client doesn’t yet support MCP OAuth.

​
Generate a key

Make sure you’ve completed Enable the MCP in your workspace first — keys are scoped to the workspace you selected there.
1

Open MCP settings in Klarity

Go to Settings → MCP in the workspace you enabled.
2

Create the key

Name it after the client you’re connecting (e.g., Claude Code – laptop, Cursor – work). Set an expiration and click Create.
3

Copy the key immediately

The full key is shown once. If you lose it, you’ll need to generate a new one.
You can view, disable, or rotate existing keys from the same screen. Keys are bound to the workspace they were generated in — to work in a different workspace, generate a separate key there (see Switching workspaces).

​
Pass the key to your client

Each client expects the key in a different place. The full request always carries: 
Authorization: Bearer <YOUR_API_KEY>
Per-client snippets:

​
Keep keys safe

Anyone with your API key can read everything your Klarity user can read. Don’t commit keys to git, share them in chat, or check them into shared configs. Prefer environment variables over inline values in JSON/TOML files, and rotate immediately if a key is exposed.

​
Switching workspaces

Each connection is scoped to a single Klarity workspace. If you belong to more than one, how you switch depends on your authentication method.

​
OAuth

Disconnect the Klarity connection in your client and reconnect. The reconnect flow shows a workspace picker, so you choose the workspace at sign-in.

​
API key

API keys are bound to the workspace they were generated in — an existing key cannot be pointed at a different workspace.
1

Enable the MCP in the other workspace

If you haven’t already, complete Enable the MCP in your workspace for the workspace you want to switch to.
2

Generate a key there

In that workspace, go to Settings → MCP and create a new API key.
3

Swap the Bearer token

Update your client to send the new key as the Bearer token. The connection now reads from the new workspace.