Skip to main content
The ish MCP server is the hosted, agent-native surface for ish: the place any MCP agent drives the platform, including general assistants with no access to your machine or filesystem. Connect to it directly — you don’t also need the CLI. It forwards the authenticated caller’s identity to api.ishlabs.io and runs each call against that user’s workspaces. A connected agent can build studies, draw an audience, run simulations, and read back what the simulated people noticed.

​
Endpoint

This page is the source of truth for the endpoint string. Other pages link here rather than restate it.
No trailing slash. A POST to https://mcp.ishlabs.io/mcp/ triggers a 307 redirect to the canonical path, and some clients (ChatGPT’s openai-mcp) do not complete a POST across that redirect, so the model sees an empty tool catalog. Always use the path without a trailing slash.

​
Transport

The server speaks MCP over streamable HTTP, mounted at /mcp. There is no SSE or stdio endpoint on the hosted server. Local runs use the same transport on a loopback port.

​
Auth

The hosted server validates inbound identity as Supabase JWTs and advertises itself as the authorization server through an OAuth proxy, so a client running dynamic client registration with a loopback redirect (VS Code, for example) completes the flow on any ephemeral port. On first connect the client runs the OAuth handshake; subsequent calls reuse the issued token. The proxy holds one fixed upstream redirect and translates the client’s per-session redirect to it.

​
Surface

The hosted server exposes 40 tools, 10 resources, and no prompts.

Tools

40 tools across 11 domains: workspace, brand, study, ask, person, chatbot, simulation, site_access, connect, upload, docs. Each carries a domain tag and a mode tag (read, write, dispatch, delete) for clients that filter the catalog.

Resources

10 ish:// resources: the docs index and pages, the authenticated identity, per-modality content types, workspace secrets, and the binary study media (screenshots, transcripts, iteration media) read on demand.
The connect tool (manage a localhost tunnel) is local-only and is hidden on the hosted server, because the server’s localhost is not the user’s machine. It appears only when you run the server on your own machine. The connect_status read tool stays available on both.
Not on the hosted MCP: your machine. The hosted server has no access to your filesystem, your localhost, or your simulators, so testing a web, iOS, or Android app that runs locally is a CLI capability. You can expose a local web build to an agent with ish connect (the tunnel runs from the CLI), but native iOS and Android runs stay on the CLI.
For the full tool and parameter tables, see the tool index and the resource reference. Per-domain tool pages are linked from the index (for example study tools and ask tools).

​
Connecting a client

To wire a specific client (Claude Code, Cursor, VS Code, Windsurf, or ChatGPT) to this endpoint, follow connect an agent. The shortest path for Claude Code:
The first connect runs the OAuth handshake (see Auth). The connect an agent page carries the per-client steps.

​
Concepts

The tools operate on a small set of shared concepts. Read these once, then the tool descriptions assume them:
  • Workspace: the top-level container for studies, asks, people, and sources.
  • Study: the persistent research artifact (modality, assignments, questions) with its iterations.
  • People: the simulated participants who experience your artifact.
  • Run vs ask: when to run a study and when to compare variants with an ask.
  • Reactions and results: the reported journey a run produces.

​
Errors

Every API failure surfaces as a tool error whose message starts with a bracketed code. Pattern-match on the prefix to branch: