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

# Connect your agent to Peeps

> Connect Claude Code, Cursor, or Codex to the Peeps MCP server. One command per client, approved once in your browser.

Connect your agent to Peeps once per machine, in whichever client you use. The connection is not per-repo, so run it from anywhere.

## First: get your organization enabled

<Warning>
  **MCP is off by default for every organization.** Nothing below will work until it is switched on, and only Peeps staff can do it — an org admin cannot self-enable.

  Email [support@peepsai.com](mailto:support@peepsai.com) with your organization name to have it turned on.
</Warning>

This is deliberate. MCP hands an external coding agent read access to your organization's failure evidence, so turning it on is a decision we make with you rather than a toggle.

Once it is on, everything below takes about two minutes.

<Steps>
  <Step title="Add the Peeps server">
    Find your client below.

    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add --transport http peeps https://app.peepsai.com/api/mcp
        ```

        Claude Code registers itself with Peeps, so there is no client id to supply.
      </Tab>

      <Tab title="Cursor">
        Add Peeps to `~/.cursor/mcp.json`, then approve the sign-in when Cursor prompts.

        ```json ~/.cursor/mcp.json theme={null}
        {
          "mcpServers": {
            "peeps": {
              "url": "https://app.peepsai.com/api/mcp",
              "auth": {
                "CLIENT_ID": "peeps-cursor",
                "scopes": ["read", "run", "edit", "publish", "offline_access"]
              }
            }
          }
        }
        ```

        <Warning>
          The `auth` block is required. Without `CLIENT_ID`, Cursor falls back to registering itself, which Peeps cannot accept — the server would install but never authorize.
        </Warning>

        Verified against Cursor IDE `3.15.19` and Agent CLI `2026.08.11`.
      </Tab>

      <Tab title="Codex">
        Two commands. Add the server, then sign in.

        ```bash theme={null}
        codex mcp add peeps --url https://app.peepsai.com/api/mcp --oauth-client-id peeps-codex
        ```

        ```bash theme={null}
        codex mcp login peeps
        ```

        The login command opens the browser approval. No other flags are needed — there is no `--transport` flag on `codex mcp add`.

        Verified against Codex CLI `0.147.0`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Approve the connection">
    The first time your agent reaches Peeps, you are sent to your browser to sign in and approve access. The consent screen names the client and lists each permission it is asking for: **Read**, **Run**, **Edit**, **Publish** and **Stay connected**.

    Sign in the way you usually do: with a login link, Google, or, if your organization uses it, **Sign in with SSO**. To set up single sign-on for your organization, see [Set up Okta](/sso/okta).

    Approve it, return to your editor, and the connection stays authorized. [What each permission allows](/mcp/access-and-approvals#the-five-permissions) explains the list line by line.
  </Step>

  <Step title="Check that it works">
    In any of the three clients, ask your agent:

    > Who am I in Peeps?

    It should list your organizations, your role in each, whether MCP is enabled for each, and the permissions this connection actually carries. If you see them, you are connected.
  </Step>
</Steps>

## Optional: the Peeps workflows

Plain English works everywhere. Peeps also serves three ready-made workflows as MCP prompts. Use them if your client lists MCP prompts.

| Prompt | What it does | What it needs |
| - | - | - |
| `peeps-troubleshoot` | Digs into a failing test and branches on the diagnosis. | A Peeps run, test case or batch URL, or an id. |
| `peeps-cover` | Compares a code change against the coverage you already have, and proposes cases for real gaps. | Nothing. It reads the change already in the conversation. |
| `peeps-import` | Imports your existing Playwright tests, keeping each file as the case's script. | The test files you want to bring in. |

In Cursor and Codex you can also install the troubleshooting and coverage workflows as agent skills. Download them from Peeps settings, under **Coding agents**, and save each one as `~/.agents/skills/<name>/SKILL.md`.

## Managing the connection

Peeps settings, under **Coding agents**, lists every client you have authorized and lets you revoke one. Reconnect from the same page if a tool ever reports that your connection lacks a permission.

After Peeps ships an update, start a new session in your agent. It reads the list of commands when a session starts, so an open session can keep following the previous instructions.

<Warning>
  Revoking stops a client renewing its access. It does not kill a token already in that client's hands — an access token stays valid until it expires, up to 15 minutes later.

  Revoking also applies to every installation authorized under that client, on every machine, not just this one.
</Warning>

<Card title="Permissions and approvals" icon="arrow-right" horizontal href="/mcp/access-and-approvals">
  What each permission allows, and what your agent asks you before it changes anything.
</Card>