> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Use hosted OAuth or an organization API key, including with headless hosted clients.

## Hosted OAuth (recommended first)

The User Intuition MCP server is available at:

```text theme={null}
https://mcp.userintuition.ai/mcp
```

Compatible clients discover OAuth automatically. Complete the authorization flow before testing a tool. Seeing the tool catalog alone is not proof of authentication because a client can discover tools before an account-scoped request succeeds.

Headless clients can instead send an organization API key to the same hosted endpoint in an `Authorization: Bearer ui_sk_…` header. The server validates the key and its scopes with the backend on every request, so revocation takes effect without a separate hosted MCP login. Call `get_account` to verify the effective workspace before running tools.

## stdio clients

Claude Desktop, Cursor, Claude Code, and VS Code can launch the MCP server locally. Set `USERINTUITION_API_KEY` to a key created under **Settings → API Keys**. New keys start with read access; choose write or paid-action permissions when creating one if the local agent needs them.

Keep API keys out of source control, screenshots, prompts, and shared configuration files. Rotate a key immediately if it is exposed.

## Authorization behavior

Every backend request is scoped to the authenticated account. Resource reads, updates, and deletes also perform ownership checks. A valid OAuth session or API key can still receive `403` or `404` when the requested resource is not accessible.

Platform admins with `users.role = admin` can call `list_organizations` and read public research across organizations. Pass `organization_id` to an MCP tool to select one for account-scoped reads or changes; it is required before changing another organization's study or using its wallet. Organization owner/admin membership alone does not grant this access. An admin API key still needs the tool's scopes and paid-action spend cap. See [platform admin access](/api-reference/platform-admins).

`read` permits study and result retrieval, including search and estimates. `write` permits non-paid changes. Paid `launch_panel` requires `write` and `panel:launch`; `send_participant_reward` requires `write` and `rewards:send`. Paid API keys also require a positive lifetime USD cap. The amount reserved for an uncertain paid operation continues to count against that cap until reconciled. OAuth clients must request the corresponding scopes for hosted tools. These grants allow a call, but a human still approves the plan and each spend through the tool workflow.

## External side effects

The surface includes paid panel launches, participant invitations, rewards, and completed-interview webhooks. Authentication makes those operations available; it does not replace product decisions or user confirmation. Agents must return and obtain approval of the current persisted plan before participant creation or paid launch, and respect each tool's safety annotations before spending money, sending a reward, registering a webhook, stopping recruitment, or deleting data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.