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

# Install the Oqoqo Plugin

> Install the Oqoqo Plugin in Codex, Claude Code, Cursor, or GitHub Copilot, sign in once, and work with Oqoqo from your AI assistant.

With the **Oqoqo Plugin**, your [AI assistant](https://docs.oqoqo.ai/reference/glossary.md#ai-assistant)—such as Codex, Claude Code, Cursor, or GitHub Copilot—can create tasks, build treatments, launch experiments, and summarize results in plain language while you work. You still use the dashboard to explore visual results and enter secrets.

The plugin bundles two pieces:

* **Oqoqo MCP server** (`https://mcp.oqoqo.ai/mcp`): exposes the same capabilities as the [CLI](https://docs.oqoqo.ai/operate/cli.md) and [Ask Oqo](https://docs.oqoqo.ai/operate/ask-oqo.md), authenticated via OAuth. (This operates your Oqoqo projects and is separate from MCP servers you evaluate as [tools](https://docs.oqoqo.ai/experiments/tools.md).)
* **Four [skills](#skills-in-the-plugin)**: teach your AI assistant how to design eval sets, write fair rubrics, set up clean baselines, and interpret comparisons accurately.

## Prerequisites

* An Oqoqo account with at least one [project](https://docs.oqoqo.ai/setup/projects.md), connected [model providers](https://docs.oqoqo.ai/setup/model-providers.md), [Oqoqo AI models](https://docs.oqoqo.ai/setup/oqoqo-ai.md), and available runs ([check your setup](https://docs.oqoqo.ai/setup/organization.md#check-your-setup)).
* ChatGPT (Codex), Claude Code, Cursor, or GitHub Copilot (for other MCP hosts, [connect without the plugin](#connect-without-the-plugin)).

## Install the plugin

Add the `oqoqo` marketplace and install `oqoqo` from the public [Oqoqo-Inc/agent-plugin](https://github.com/Oqoqo-Inc/agent-plugin) repository.

> [tab] ChatGPT (Codex)
>
> ```bash theme={null}
> codex plugin marketplace add Oqoqo-Inc/agent-plugin \
>   --sparse .agents/plugins \
>   --sparse distributions/openai
> codex plugin add oqoqo@oqoqo
> ```

> [tab] Claude Code
>
> ```bash theme={null}
> claude plugin marketplace add Oqoqo-Inc/agent-plugin \
>   --scope user \
>   --sparse .claude-plugin distributions/claude-code
> claude plugin install oqoqo@oqoqo --scope user
> ```
>
> Then start Claude Code and run `/mcp` to [sign in](#sign-in).

> [tab] Cursor
>
> Run these commands in Cursor Agent CLI (`cursor-agent` also installs plugins for Cursor):
>
> ```bash theme={null}
> cursor-agent plugin marketplace add https://github.com/Oqoqo-Inc/agent-plugin.git
> cursor-agent
> ```
>
> In Cursor Agent, enter `/plugin`, open **Marketplace**, select **oqoqo**, press Enter, and choose user scope. Then run `/mcp`, select **oqoqo**, and choose **Login** to [sign in](#sign-in).

> [tab] GitHub Copilot
>
> ```bash theme={null}
> copilot plugin marketplace add Oqoqo-Inc/agent-plugin
> copilot plugin install oqoqo@oqoqo
> ```
>
> Then start `copilot` and run `/mcp auth oqoqo` to [sign in](#sign-in).

The same install commands appear in the dashboard under **Automate → Oqoqo Plugin (MCP)**. The plugin stores no local credentials, and its skills reference `https://docs.oqoqo.ai/llms.txt`.

![Install the Oqoqo Plugin page with a tab for each AI assistant, the plugin commands, and Or add MCP directly.](https://mintcdn.com/oqoqo/YO1ysyUx4SPwBwoz/images/screenshots/install-mcp-light.png?fit=max\&auto=format\&n=YO1ysyUx4SPwBwoz\&q=85\&s=231b77ef2792a2a6be86618667442ef0)

## Sign in

The first time your host connects, it opens Oqoqo sign-in in your browser so your AI assistant acts with your permissions ([sign-in rules](https://docs.oqoqo.ai/mcp-server/overview.md#sign-in)).

| Host | Sign-in step |
| - | - |
| ChatGPT (Codex) | Opens automatically on first use, or run `codex mcp login oqoqo`. |
| Claude Code | Run `/mcp` and complete sign-in for `plugin:oqoqo:oqoqo`. |
| Cursor | In `cursor-agent`, run `/mcp`, select **oqoqo**, and choose **Login**. |
| GitHub Copilot | In an interactive `copilot` session, run `/mcp auth oqoqo`. |

Start a new session and ask *"Who am I signed in to Oqoqo as?"*—your assistant calls **Get the signed-in user and organization** ([`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity)) to verify the connection.

## Turn on tool approval

In your host's settings, disable auto-approval for Oqoqo write tools—especially **Launch an experiment** ([`launch_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#launch_experiment))—so your assistant prompts you before executing them ([Approvals](https://docs.oqoqo.ai/mcp-server/overview.md#approvals)).

> [!WARNING]
>
> Launching an experiment spends runs from your balance with no server-side confirmation prompt; only your host's tool approval stops an unintended launch.

## What your AI assistant can do

| Area | Capabilities |
| - | - |
| Define tasks and treatments | Search catalog; author tasks, files, machines, tools, and treatments; import public GitHub folders |
| Run experiments | Preflight plans, launch, poll progress, relaunch, cancel, and schedule recurring runs |
| Read results | Summarize pass rates, check statistical comparisons and Briefs, and read run profiles, trajectories, and frictions |
| Organize and share | Tag records, publish public experiment links, and check notifications and run balance |

For any step requiring a secret or payment, your assistant returns a direct dashboard link ([secrets stay in the dashboard](https://docs.oqoqo.ai/mcp-server/overview.md#secrets-stay-in-the-dashboard)). See [Plugin (MCP) tools](https://docs.oqoqo.ai/mcp-server/tools.md) for all 80 tools.

> [!NOTE]
>
> Always name the project in your prompt. The plugin does not store a default project across calls ([Projects](https://docs.oqoqo.ai/mcp-server/overview.md#projects)).

### Try a first prompt

```text theme={null}
Show my Oqoqo projects. For the first one, list its catalog and summarize its recent experiments.
```

Then try creating and running an experiment:

```text theme={null}
In my Payments project, draft a task for our checkout flow, launch a small experiment with a baseline and our MCP server, and explain the Matrix and top frictions when it finishes.
```

## Build an eval set and read its results

Your AI assistant can read a public documentation URL, or local docs, READMEs, and OpenAPI files directly inside your repository:

**1. Build the eval set**

Ask your AI assistant to generate tasks, a machine, tools, and treatments from your docs:

```text wrap theme={null}
Build an Oqoqo eval set for Acme Payments from its docs at https://docs.example.com. Use my Oqoqo project Acme evals.
```

The `product-eval-authoring` skill creates the resources via [`bulk_author_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#bulk_author_resources), runs [`preflight_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#preflight_experiment), and lists dashboard links for any secrets needed.

**2. Enter secrets in the dashboard**

Open each returned link to add API keys or OAuth connections, and confirm your target agents are enabled under **Manage → Agents**.

**3. Launch the experiment**

```text wrap theme={null}
Check the eval set again and plan a launch with two trials on Claude Code and Codex. Tell me how many runs it uses, and wait for my go-ahead before you launch.
```

The `product-eval-results` skill previews the run count, launches with [`launch_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#launch_experiment) after your approval, and monitors progress with [`get_experiment_status`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment_status). For larger experiments, you can watch live progress at the returned `dashboardUrl` or ask your assistant to check status again later.

**4. Review the results**

```text wrap theme={null}
Compare each treatment with the baseline, and list the top frictions and where to fix each one.
```

Your assistant calls [`analyze_results`](https://docs.oqoqo.ai/mcp-server/runs-and-results#analyze_results) and [`list_frictions`](https://docs.oqoqo.ai/mcp-server/frictions#list_frictions). Open the experiment in the dashboard anytime to view **Matrix** and **Frictions** visually.

## Skills in the plugin

Your assistant loads each skill automatically when relevant (or when you name it). See [Plugin (MCP) skills](https://docs.oqoqo.ai/mcp-server/skills.md) for full workflows and tool lists.

| Skill | Purpose |
| - | - |
| `product-eval-authoring` | Build a complete eval set (tasks, machine, files, tools, treatments) from a product's docs |
| `product-eval-tasks` | Write tasks and fair rubrics, or review existing rubrics |
| `product-eval-setup` | Design clean machines, isolated treatments, and seeded test data |
| `product-eval-results` | Launch experiments, wait for completion, and interpret Comparisons, Briefs, and frictions |

## Update or remove the plugin

### Update the plugin

MCP tools update automatically on Oqoqo's server, while locally installed skills update when your host updates the plugin:

* **Codex:** updates automatically on startup.
* **Claude Code:** updates automatically after you enable auto-update under `/plugin → Marketplaces → oqoqo → Enable auto-update` (run `/reload-plugins` after an update).
* **Cursor and GitHub Copilot:** require manual updates.

On plugin v1.3.17+, [`get_project_context`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_project_context) returns `pluginUpdate` (`recommended` or `required`) when a skill update matters, so your assistant alerts you with your host's commands.

> [tab] ChatGPT (Codex)
>
> Start a new session or run:
>
> ```bash theme={null}
> codex plugin marketplace upgrade oqoqo
> ```
>
> Check version with `codex plugin list -m oqoqo`.

> [tab] Claude Code
>
> Run both commands in order, then restart or run `/reload-plugins`:
>
> ```bash theme={null}
> claude plugin marketplace update oqoqo
> claude plugin update oqoqo@oqoqo --scope user
> ```
>
> Check version with `claude plugin list`.

> [tab] Cursor
>
> ```bash theme={null}
> cursor-agent plugin marketplace update oqoqo
> ```
>
> Cursor Agent cannot upgrade an installed plugin directly—if a new session still uses the old version, run `/plugin`, uninstall **oqoqo** under **Installed**, and reinstall from **Marketplace**.

> [tab] GitHub Copilot
>
> ```bash theme={null}
> copilot plugin update oqoqo@oqoqo
> ```
>
> Start a new session; check version with `copilot plugin list`.

### Turn off or remove the plugin

Disabling or removing the plugin leaves your Oqoqo organization unchanged. Sign out first if you also want to clear cached OAuth tokens.

> [tab] ChatGPT (Codex)
>
> Toggle off via `/plugins` (Space on **oqoqo**) or `enabled = false` in `~/.codex/config.toml`. Sign out and remove:
>
> ```bash theme={null}
> codex mcp logout oqoqo
> codex plugin remove oqoqo@oqoqo
> codex plugin marketplace remove oqoqo
> ```

> [tab] Claude Code
>
> Disable with `claude plugin disable oqoqo@oqoqo` (`enable` to resume). To remove after clearing auth in `/mcp`:
>
> ```bash theme={null}
> claude plugin uninstall oqoqo@oqoqo
> claude plugin marketplace remove oqoqo
> ```

> [tab] Cursor
>
> Disable the server in `/mcp → oqoqo → Disable`. To uninstall, run `/plugin → Installed → oqoqo → Uninstall` and optionally remove the marketplace (this removes it across all Cursor apps sharing your account):
>
> ```bash theme={null}
> cursor-agent plugin marketplace remove oqoqo
> ```

> [tab] GitHub Copilot
>
> Disable with `copilot plugin disable oqoqo@oqoqo` (requires recent Copilot CLI; `enable` to resume). To remove:
>
> ```bash theme={null}
> copilot plugin uninstall oqoqo@oqoqo
> copilot plugin marketplace remove oqoqo
> ```

## Troubleshoot the plugin

> [accordion] An install command fails
>
> * **Unknown command/flag:** update your host CLI first, or [connect without the plugin](#connect-without-the-plugin).
> * **Marketplace already exists:** skip the `marketplace add` line and run the install command.
> * **Network/download errors:** verify access to `github.com`.

> [accordion] Sign-in does not open or finish
>
> Run the host's [sign-in step](#sign-in) (`plugin:oqoqo:oqoqo` in Claude Code, `oqoqo` elsewhere). If you belong to multiple organizations and calls fail with `organization_ambiguous`, sign out and sign back in while selecting the right organization.

> [accordion] Oqoqo tools or skills are missing
>
> Start a fresh session, verify the plugin is enabled (`list` commands or `/plugin`), and confirm `/mcp` shows an active sign-in. If tools work without skills, you have a direct MCP connection—switch to the plugin or [install skills separately](#add-the-skills-without-the-plugin).

> [accordion] The plugin and a direct connection are both set up
>
> Having both can duplicate tools or hide `plugin:oqoqo:oqoqo` (Claude Code hides the plugin's server when a direct `oqoqo` entry exists). Remove the direct entry and restart your session:
>
> | Host | Remove direct connection |
> | - | - |
> | ChatGPT (Codex) | `codex mcp remove oqoqo` |
> | Claude Code | `claude mcp remove oqoqo` |
> | Cursor | Delete `oqoqo` from `~/.cursor/mcp.json` or `.cursor/mcp.json` |
> | GitHub Copilot | `copilot mcp remove oqoqo` |

## Connect without the plugin

Use direct MCP when your host lacks plugin support, to add the optional `oqoqo-product-docs` search server (`https://docs.oqoqo.ai/mcp`), or to authenticate headless runs with an API key. (Never configure both the plugin and a direct `oqoqo` connection in the same host.)

### Add MCP directly

> [tab] ChatGPT (Codex)
>
> ```bash theme={null}
> codex mcp add oqoqo --url https://mcp.oqoqo.ai/mcp
> codex mcp login oqoqo
> codex mcp add oqoqo-product-docs --url https://docs.oqoqo.ai/mcp
> ```

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http --scope user oqoqo https://mcp.oqoqo.ai/mcp
> claude mcp add --transport http --scope user oqoqo-product-docs https://docs.oqoqo.ai/mcp
> ```
>
> Then start Claude Code, run `/mcp`, and sign in to `oqoqo`.

> [tab] Cursor
>
> Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json`):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "oqoqo": { "type": "http", "url": "https://mcp.oqoqo.ai/mcp" },
>     "oqoqo-product-docs": { "type": "http", "url": "https://docs.oqoqo.ai/mcp" }
>   }
> }
> ```
>
> Then run `cursor-agent mcp login oqoqo && cursor-agent mcp enable oqoqo`.

> [tab] GitHub Copilot
>
> ```bash theme={null}
> copilot mcp add --transport http oqoqo https://mcp.oqoqo.ai/mcp
> copilot mcp add --transport http oqoqo-product-docs https://docs.oqoqo.ai/mcp
> ```
>
> Start `copilot` and run `/mcp auth oqoqo`.

### Sign in with an API key

In headless CI or automated machines, store a [personal API key](https://docs.oqoqo.ai/setup/profile.md#api-keys) in `OQOQO_API_KEY` and send `Authorization: Bearer <key>` instead of OAuth (invalid or revoked keys return `401`).

> [tab] ChatGPT (Codex)
>
> Add to `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.oqoqo]
> url = "https://mcp.oqoqo.ai/mcp"
> bearer_token_env_var = "OQOQO_API_KEY"
> ```

> [tab] Claude Code
>
> Save `oqoqo-mcp.json` and pass it with `claude --mcp-config oqoqo-mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "oqoqo": {
>       "type": "http",
>       "url": "https://mcp.oqoqo.ai/mcp",
>       "headers": { "Authorization": "Bearer ${OQOQO_API_KEY}" }
>     }
>   }
> }
> ```

### Add the skills without the plugin

Install the four skills standalone for direct MCP or CLI workflows (omit `-g` for project-local install; never run this alongside the plugin):

```bash theme={null}
npx skills add Oqoqo-Inc/agent-plugin --skill '*'
```

Update with `npx skills update` or remove with `npx skills remove`.

## Next steps

> [card] [Measure a tool's impact](https://docs.oqoqo.ai/guides/measure-tool-lift.md)
>
> Run a complete lift experiment from your AI assistant.

> [card] [Plugin (MCP) reference](https://docs.oqoqo.ai/mcp-server/overview.md)
>
> Learn auth, approvals, paging, polling, and error handling.

> [card] [Plugin (MCP) tools](https://docs.oqoqo.ai/mcp-server/tools.md)
>
> Browse all 83 tools by area.

> [card] [Use the CLI](https://docs.oqoqo.ai/operate/cli.md)
>
> Automate experiments from your terminal and CI.


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