> ## 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.
# Quickstart
> Connect with hosted OAuth first, or use the local stdio setup for Claude Desktop, Cursor, Claude Code, and VS Code.
## 1. Choose a connection
Use the hosted Streamable HTTP endpoint with OAuth when your client supports it:
```text theme={null}
https://mcp.userintuition.ai/mcp
```
The client discovers OAuth automatically. Sign in and authorize User Intuition when prompted.
For a smaller catalog, use `https://mcp.userintuition.ai/core/mcp` for the 33-tool research workflow, `https://mcp.userintuition.ai/read-only/mcp` for 25 read-only tools, or `https://mcp.userintuition.ai/compact/mcp` for 41 tools with grouped administrative operations. Authorize each endpoint separately. The full URL above retains all 50 tools. Local stdio clients can append `--profile core`, `--profile read-only`, or `--profile compact` to the server command.
To try study design and reports in staging, connect to `https://mcp.sandbox.userintuition.ai/mcp` with a staging account. Follow the [sandbox quickstart](/api-reference/staging-quickstart) for Test with AI, three synthetic responses, and the participant-link limitation.
Local stdio remains supported for clients that need a local process. Create a key under **Settings → API Keys** at [app.userintuition.ai](https://app.userintuition.ai). Keys start with `ui_sk_`.
## 2. Connect your client
In ChatGPT, enable developer mode under **Settings → Apps & Connectors → Advanced**, then create a connector:
* **MCP Server URL:** `https://mcp.userintuition.ai/mcp`
* **Authentication:** OAuth (auto-discovered)
If you previously connected the old **User Intuition Human Signal** server, remove that custom connector and create it again. Existing connectors can retain obsolete tools after the server is upgraded.
```bash theme={null}
codex mcp add userintuition --url https://mcp.userintuition.ai/mcp
codex mcp login userintuition
```
The add command may start OAuth immediately. If it does, complete that flow; the separate login command is only needed when authorization is still pending. Restart Codex or open a new task after setup so it loads the tool catalog.
Add this server to `~/Library/Application Support/Claude/claude_desktop_config.json`, then fully restart Claude Desktop:
```json theme={null}
{
"mcpServers": {
"userintuition": {
"command": "npx",
"args": ["-y", "@userintuition-ai/mcp@latest"],
"env": {
"USERINTUITION_API_KEY": "ui_sk_your_key_here"
}
}
}
}
```
Add the same `mcpServers` entry to `.cursor/mcp.json`, replace the example key, and restart Cursor.
```bash theme={null}
claude mcp add userintuition -- npx -y @userintuition-ai/mcp@latest
```
Make `USERINTUITION_API_KEY` available to the environment that launches Claude Code. Do not commit the key to your repository.
Add the server command and environment variable under `"mcp.servers"` in `.vscode/settings.json`, then reload the window.
## 3. Verify the connection
Ask your client:
> List my User Intuition studies.
The agent should call `get_account`. A successful account-scoped response confirms authentication; merely seeing tool names does not. The current surface contains 50 tools, including `queue_customize_study`, `review_study`, `search_research`, and `answer_research`, and excluding `ask_humans`.
## 4. Give the agent a workflow
Connection proves the tools work. A Skill tells the agent how to use them reliably.
Install the [create-study-from-brief Skill](/skills/create-study-from-brief), then ask the agent to use it. The Skill adds the question order, readiness checks, plan review, and approval gates needed for a safe study-creation flow.
Add the reusable study-design workflow to your AI client.
Understand the workflow rules already advertised by the server.
After installing the Skill, try:
> Use the create-study-from-brief Skill to help me design a Panel study about why trial users do not activate. Dry-run the panel cost, but do not launch without my confirmation.
For a healthy end-to-end run, the agent should keep the study name to 40 characters, ask you to choose the recruiting method when it is missing, create a metadata draft, and pass your research brief to `queue_customize_study`. Poll `get_customize_study_job` until it succeeds and read its `result`; use synchronous `customize_study` for a native concept image. Omitted interview settings default to an English voice interview with Elliot. The default `decisions: "human"` relays `questions[]` to you. If you delegate research-design choices, `decisions: "agent"` lets the planner proceed with assumptions and report them back; remaining required questions still come back in `questions[]`. The agent must then call `get_study`, return the complete persisted plan for review, and obtain approval of that exact version before creating BYOP participants or launching paid Panel recruitment. A Panel launch also requires an explicit single country and separate approval of its estimate.
Public API MCP tools return full JSON in `structuredContent.result`; supplemental tools use `structuredContent` directly. Text content is a short summary. Clients that cannot read structured results can set `MCP_FULL_TEXT_RESULTS=true` in their local server environment.
## Troubleshooting
If the tools are missing after hosted OAuth setup, restart the client or start a new chat/task. For stdio, restart the client and force a fresh package download with `npx -y @userintuition-ai/mcp@latest`. See [Troubleshooting](/mcp-server/guides/troubleshooting) for authentication and cache checks.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.