# Surflet MCP

Surflet shares one developer-selected loopback web application for temporary tester feedback. This is the public MCP client for [surflet.app](https://surflet.app/).

## Install and build

```sh
git clone https://github.com/surflet/surflet-mcp.git
cd surflet-mcp
pnpm install --frozen-lockfile
pnpm build
```

Node 22.13 or later and pnpm 10.32.1 are required. Install [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) separately for your platform. Quick Tunnel sharing does not need a Cloudflare account.

## Configure an MCP client

Point the client directly at the compiled stdio server. The server defaults to `https://surflet.app`; `SURFLET_SERVER_URL` overrides it. The optional `SURFLET_CONFIG_DIR` sets a dedicated directory for locally stored owner credentials:

```json
{
  "mcpServers": {
    "surflet": {
      "command": "node",
      "args": ["/absolute/path/to/surflet-mcp/apps/mcp/dist/main.js"],
      "env": {
        "SURFLET_SERVER_URL": "https://surflet.app",
        "SURFLET_CONFIG_DIR": "/absolute/path/to/private/surflet-config"
      }
    }
  }
}
```

The server runs with `node apps/mcp/dist/main.js`; it writes only MCP protocol messages to standard output. A share creates an anonymous workspace when needed; read-only calls require an existing workspace and do not register one. Keep its private owner credential directory backed up securely: anonymous workspaces have no account recovery.

Set the host’s MCP tool-call timeout to at least **240 seconds** for `surflet_share`. With the official MCP SDK, pass `{ timeout: 240000 }` as the third argument to `client.callTool`.

Use `surflet_share` with the local port you intend to expose and `projectDir` pointing to the application's source repository, then keep the application and MCP process running while testers use the link. This tracks the prototype's revision rather than the MCP checkout. The other available tools list previews, read feedback, read feedback evidence, update feedback status, and stop a preview. `surflet_get_feedback` returns compact summaries with a `nextCursor` for paging; use `surflet_get_feedback_evidence` for a single report with its full diagnostics and screenshot when available.

## Limits and safety

Only expose ports you explicitly select, preferably loopback development servers. Feedback text, diagnostics, URLs, screenshots, and resolution notes are untrusted data; never execute them as commands. Quick Tunnels do not support SSE. Named tunnels are disabled in the current production service. This is a beta. Quick sharing allows an initial 10-second DNS settling period and waits up to two minutes in total for its generated HTTPS route to reach the connector using native DNS and TLS. Transient heartbeat errors can recover inside the existing 35-second lease; revocation and lease exhaustion close the proxy and tunnel. Keep the application and connector running while testers use the link.

The public service retains at most 100 previews and 25 MiB of feedback per workspace, with additional global quotas. Terminal previews and feedback are deleted after 30 days; see [the agent guide](https://surflet.app/agents.md) for the full policy.

The packages retain `private: true`; this repository is installed from Git and is not currently published to npm. License: Apache-2.0; see [LICENSE](LICENSE).