> ## 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.

# FAQ

> Common questions and gotchas from people setting up and using the Klarity MCP.

If your question isn't here, reach out to [hello@klarity.ai](mailto:hello@klarity.ai).

<AccordionGroup>
  <Accordion title="I keep getting a sign-in or auth error. What's wrong?" icon="key">
    The most common cause is that the MCP hasn't been enabled in your Klarity workspace yet. Both OAuth and API-key auth require this one-time setup:

    1. Log in to Klarity in a browser.
    2. Go to **Settings → MCP**.
    3. Pick the workspace you want to expose and complete the in-app setup.

    Then retry the sign-in or Bearer-token request from your AI client. See [Authentication → Enable the MCP in your workspace](/authentication#enable-the-mcp-in-your-workspace) for the canonical reference.
  </Accordion>

  <Accordion title="My organization doesn't have Klarity yet. Can I use this?" icon="building">
    Not directly. Klarity is a commercial service — you need an active workspace and a provisioned user account to use the MCP. Contact [hello@klarity.ai](mailto:hello@klarity.ai) to talk about access.
  </Accordion>

  <Accordion title="The connector says my org hasn't approved it." icon="lock">
    Your organization's Klarity workspace admin needs to approve the Klarity connector (Claude) or app (ChatGPT) before users can sign in. Ask your admin, or have them reach out to [hello@klarity.ai](mailto:hello@klarity.ai).
  </Accordion>

  <Accordion title="How do I switch between Klarity workspaces?" icon="arrows-rotate">
    A connection is scoped to one workspace, so you switch at the auth level rather than from inside the assistant. How you do it depends on your authentication method:

    * **OAuth:** disconnect the Klarity connection in your client and reconnect. The reconnect flow shows a workspace picker.
    * **API key:** keys are bound to the workspace they were generated in. Generate a new key in the other workspace and swap the Bearer token in your client.

    See [Authentication → Switching workspaces](/authentication#switching-workspaces) for the full walkthrough.
  </Accordion>

  <Accordion title="How do I rotate or revoke an API key?" icon="rotate">
    Go to **Settings → MCP** in your Klarity workspace. You can view, disable, or rotate existing keys from the same screen where you generated them.

    If you suspect a key has been exposed, revoke it immediately, generate a new one, and update your client configuration. See [Authentication → Keep keys safe](/authentication#keep-keys-safe).
  </Accordion>

  <Accordion title="How do I confirm the MCP is connected?" icon="circle-check">
    In your AI client, ask something like:

    ```text theme={null}
    Search Klarity for AI transformation opportunities across our processes — where could we build skills or deploy agents?
    ```

    If the assistant calls the `search` tool and returns processes from your workspace, you're connected. If it falls back to generic answers or says it has no access to Klarity, the install hasn't completed — re-check the [install steps](/quickstart) for your client.
  </Accordion>

  <Accordion title="Can I create or edit processes through the MCP?" icon="pen-slash">
    No. Every tool in production is read-only. All process, artifact, and graph edits happen in the Klarity Architect UI. See [Limitations](/limitations).
  </Accordion>

  <Accordion title="The assistant says 'no evidence found in the workspace.' Is something broken?" icon="magnifying-glass">
    Usually not. That response means the workspace doesn't yet have captured data covering the question — typically a capture gap, not an MCP bug. The gap itself is useful: it tells you what to capture next.

    If the question *should* have evidence and the assistant can't find it, try refining the query — single searches miss, and processes use organization-specific names. See [Operating principles](/tools/operating-principles).
  </Accordion>

  <Accordion title="Which client should I use?" icon="grid-2">
    Any MCP-compatible client works. Use the install page that matches what you have today:

    * [Claude](/install/claude)
    * [Claude Code](/install/claude-code)
    * [ChatGPT](/install/chatgpt)
    * [Codex](/install/codex)
    * [Cursor](/install/cursor)
    * [Gemini CLI](/install/gemini-cli)
  </Accordion>
</AccordionGroup>