Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.klarity.ai/llms.txt

Use this file to discover all available pages before exploring further.

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. You can switch workspaces from inside the AI client later using switch_mcp_workspace.

​
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

If you’re a user in more than one Klarity workspace, the assistant can switch between them at runtime using switch_mcp_workspace. This is the only write tool exposed in production, and it only affects which workspace the current session reads from. See Workspace tools for the details.