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

# Replit

> Connect Replit's agent to the hosted ish MCP server, and point a study at a Replit URL ish can actually reach.

Wire Replit's agent to the hosted ish MCP server so it can call ish tools
(`study_create`, `study_add_iteration`, `study_run`, and the rest) while you build. The
server lives at `https://mcp.ishlabs.io/mcp`, speaks streamable HTTP, and signs you in
over OAuth on first connect, so no token lands in a config file. For the full add
mechanism and the OAuth handshake, see [connect an agent](/start/connect-an-agent).

The one thing that differs for Replit: ish runs simulated people from the cloud, so the
study URL must load **without your Replit session**. The in-editor preview is gated to
you, so a URL that works in your tab fails silently for ish. Most of this page is about
getting that URL right.

<Note>
  **Connect Replit.** Add the ish server inside Replit's MCP settings using the URL
  `https://mcp.ishlabs.io/mcp`. The "Copy MCP server URL" action in this page's
  "..." menu grabs it for you. Then point your study at a URL ish can reach, as
  below.
</Note>

## Connect

Add the ish server inside Replit's MCP settings, pointing at the hosted endpoint:

```
https://mcp.ishlabs.io/mcp
```

The agent signs in over OAuth on first connect. ish reads the `clientInfo` Replit sends
in the MCP handshake, recognizes the `replit` client, and tailors the URL guidance below
to Replit's webview and deploy paths.

<Warning>
  Use `https://mcp.ishlabs.io/mcp` with no trailing slash. The `/mcp/` form triggers a
  redirect (HTTP 307) that some clients will not follow on a POST, leaving the agent with
  an empty tool list.
</Warning>

### Confirm the connection

Ask the agent a read-only question. A read confirms the connection without drawing any
credits:

```text theme={null}
Use the ish tools to confirm who I am and list my workspaces.
```

The agent calls `workspace_get` and reports your [workspaces](/concepts/workspace) back.
A brand-new account shows an empty list, which is still a successful connection.

<Check>
  The agent returns a workspace list (or an explicit empty list) instead of "no ish tools
  available". That means the OAuth sign-in landed and the tools are live.
</Check>

## Point a study at a reachable URL

When you create an [interactive iteration](/concepts/iteration) against a Replit URL, ish
has to load that URL from a cloud browser that does not carry your Replit session. The
trap: a Replit preview URL is a public hostname, so it passes ish's localhost check, yet
still shows a login wall to anyone but you. Pick the link type that loads without your
session.

| Replit URL                       | Reachable for ish?                | Use it                           |
| -------------------------------- | --------------------------------- | -------------------------------- |
| In-editor preview pane           | No, gated to your session         | Open the webview or deploy first |
| Public `.replit.dev` webview URL | Yes, while the app is running     | Good for a quick run             |
| Deployment URL                   | Yes, served by Replit Deployments | Best for a study you reuse       |

<Steps>
  <Step title="Get a public URL in Replit">
    Open the app's `.replit.dev` webview in its own browser tab and copy that URL, or use
    Replit Deployments and copy the deployment URL. The webview URL serves while the app
    is running; the deployment URL is the durable one for a study you run more than once.
  </Step>

  <Step title="Create the iteration against that URL">
    Tell the agent to add an interactive iteration pointed at the URL. Under the hood it
    calls `study_add_iteration` with `platform="browser"` and the public `url`. You set
    this once per study; later runs reuse the same iteration.

    <CodeGroup>
      ```text Ask Replit theme={null}
      Create an interactive study for my workspace and add an iteration pointed at
      https://my-app.replit.dev, then run it for five people.
      ```

      ```json study_add_iteration args theme={null}
      {
        "study_id": "s-b2c",
        "name": "Webview build",
        "modality": "interactive",
        "platform": "browser",
        "url": "https://my-app.replit.dev"
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the reactions">
    After `study_run` completes, ask the agent for the summary. `study_get` with
    `view="summary"` returns the journey: what people noticed, where they got stuck, and
    the reasoning behind each reaction. You get a narrative, not a single score.
  </Step>
</Steps>

### What ish tells the agent

ish steers the agent for you. Because Replit's handshake identifies the `replit` client,
the `study_add_iteration` response carries a `notes` hint that names Replit's own reach
paths: use the app's public `.replit.dev` webview URL, or Deploy and use the deployment
URL, not the in-editor preview. ish also recognizes Replit hosts (`.replit.dev`,
`repl.co`) on the study URL itself, so the same hint fires when the agent points a study
at one of those hosts even from a different client.

<Note>
  The `.replit.dev` webview is reachable only while the app is running in your workspace.
  If you stop the repl, a run that worked before will fail to load the page. Deploy for a
  URL that stays up.
</Note>

## When the page needs a login you cannot remove

If the part of the app under test sits behind a real sign-in that you cannot deploy
around, register the access once on the workspace instead of fighting the gate. Then
every interactive study you point at that origin reuses it.

<CodeGroup>
  ```text Ask Replit theme={null}
  Register a session cookie for my deployed origin so ish can load the gated page, then run
  the study.
  ```

  ```python site_access_set theme={null}
  site_access_set(workspace_id="w-6ec", method="cookie",
                  name="session", value="abc123")
  ```
</CodeGroup>

ish can sign in three ways: HTTP basic auth, a session cookie, or a login form the
participant fills in. See [site access](/concepts/site-access) for which method matches
your gate and how an origin gets bound.

## Share the results

Replit's agent can create and run studies, but it cannot mint a public results link.
Sharing is a [CLI](/cli/overview) action: `ish study share` returns a public, no-login
`share_url` to paste into an email or hand to a stakeholder. See
[sharing results](/concepts/sharing) for the lifecycle and what a viewer sees.

<Note>
  A share link points at one study's results. The Replit URL above points at the app the
  simulation experiences. Two different links for two different jobs.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The agent reports no ish tools" icon="plug">
    The OAuth step did not complete. Reconnect the ish server in Replit's MCP settings,
    approve the sign-in in your browser, then ask again. Confirm the URL has no trailing
    slash.
  </Accordion>

  <Accordion title="Every simulated person bounces off a login wall" icon="lock">
    The study is pointed at a gated URL. The in-editor preview loads only with your
    session. Switch the iteration to the public `.replit.dev` webview URL or a deployment
    URL, or register a login with `site_access_set`.
  </Accordion>

  <Accordion title="A run that worked before fails now" icon="power-off">
    The `.replit.dev` webview serves only while the repl is running. Start the app again
    and rerun, or deploy the app and point the iteration at the deployment URL for a URL
    that stays up.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Run a study" icon="play" href="/mcp/generated/tools-study">
    Every parameter for `study_create`, `study_add_iteration`, and `study_run`.
  </Card>

  <Card title="Site access" icon="lock" href="/concepts/site-access">
    Reach a gated URL with basic auth, a cookie, or a login form.
  </Card>

  <Card title="Sharing results" icon="share" href="/concepts/sharing">
    Mint a public, no-login link to a study's results from the CLI.
  </Card>

  <Card title="Other clients" icon="grid-2" href="/integrations">
    Wire Lovable, Bolt, v0, Claude Code, and more.
  </Card>
</Columns>