Connect your app to Telesis

One setup prompt

Paste this prompt into an app that supports remote MCP and OAuth. It configures the endpoint and opens the generic connection page. Sign in, choose permissions and optionally enable MCP call tracing. Configuration writes and tracing default off; organization roles always apply.

You still approve access in your browser. Use the plugin or the direct connection to avoid duplicate tools. The optional local CLI is needed only for local scripts, localhost and Docker execution.

Connect this app to Telesis using the remote MCP endpoint https://api.telesis.dev/mcp. Reuse an existing Telesis connection if present. Use the app's native OAuth flow and open the Telesis connection page so I can sign in, choose permissions, and configure MCP call tracing. Never ask me to paste tokens or create a duplicate connection. If you cannot configure this app directly, give me the exact manual connection steps. After authorization, call connection_status and confirm the granted scopes and tracing setting. Playwright recording is selected per tool call with record_trace. Do not create checks or recurring monitoring during setup.

Codex: one command

Current CLI versions open OAuth during mcp add. If the connection already exists, use codex mcp login telesis_hosted to reconnect and change permissions or tracing. Start a new chat to load newly added tools. The plugin uses the same server name; do not add a duplicate direct entry when it is installed.

codex mcp add telesis_hosted --url https://api.telesis.dev/mcp

Claude Code: one command

This command registers the connection for your user and opens OAuth. If already configured, run only claude mcp login telesis_hosted. Older versions without mcp login can authenticate from /mcp inside the app. In a remote connector settings screen, enter the same endpoint URL and choose Connect.

claude mcp add --scope user --transport http telesis_hosted https://api.telesis.dev/mcp && claude mcp login telesis_hosted

Choose the right tracing control

Trace MCP calls is selected during onboarding. It applies to requests from that connection and persists across token refresh. connection_status reports tracing. Diagnostics contain call IDs, timing, outcomes and, when exported, a trace ID. Tool arguments, results and credentials are excluded. Change the preference in Connected apps at /connect, or reconnect; ordinary operational logs are unaffected.

Playwright browser tracing is separate: pass record_trace on the actual trigger_check call. True enables it for that run, false disables it, and omission uses the saved setting. This does not change the saved script, configuration or schedule. The option is only valid for Playwright checks.

Browser traces can include private page and network data. Enable them for a requested debugging run. Read get_check_result for artifact metadata, then use get_check_result_artifact to fetch the relevant archive. The local run_check tool also supports record_trace; authenticated local recordings additionally require allow_sensitive_artifacts.

{
  "id": "<saved-playwright-check-id>",
  "record_trace": true
}

Manage connected apps

Sign in at /connect to view your active connections, permissions and expiration dates. Refresh after authorizing a new app. Toggle Trace MCP calls to apply the setting to subsequent calls. Playwright recording stays a per-run choice.

Disconnect app asks for confirmation, then revokes the connection's access and refresh credentials. The app must ask for your approval to reconnect. Changing permissions also requires fresh consent. App names are supplied by the connecting app.

Run a saved cloud E2E check

Call connection_status, list_organizations, list_services and list_checks to select the right saved check. Read get_check before calling trigger_check. The job ID acknowledges queuing; it does not mean the test passed.

Pass the returned jobId to wait_for_run or get_run as job_id. The result belongs to that exact execution and includes its originating MCP call and trace IDs. Fetch private recordings with get_run_artifact only when needed. For older jobs without run records, fall back to list_check_results filtered by trigger time and report any ambiguity.

The hosted server has 26 tools, the run_e2e prompt, and telesis://guides/e2e. Creating a check enables recurring monitoring; use run_playwright for a new one-off browser test without a monitor or schedule.

{
  "mcpServers": {
    "telesis_hosted": { "type": "http", "url": "https://api.telesis.dev/mcp" }
  }
}

Run a one-off browser test

Select an organization, then call run_playwright with org_id, a fresh request_id UUID, a public HTTP(S) url, and a Playwright script up to 64 KiB. Reuse the request ID for identical retries. Set record_trace on this call when browser recording is wanted; it defaults off. The timeout defaults to 30 seconds and allows up to 120 seconds.

Execution requires run permission and write/admin/owner organization membership. It creates no recurring check, changes no schedule, and does not affect uptime or alerts. Each organization allows two pending one-off runs and 60 requests per hour.

Use wait_for_run or get_run with the returned job_id. queued is pending, dispatch_failed means queue acknowledgement failed, and unconfirmed means no result arrived before the deadline. None means the test passed. Runs and private artifacts are retained for seven days. Failure traces take priority over passing recordings; omission warnings name the affected artifact and limit.

{
  "org_id": "<organization-uuid>",
  "request_id": "<fresh-uuid>",
  "url": "https://telesis.dev",
  "script": "test('home', async ({page}) => { await page.goto('/'); await expect(page).toHaveTitle(/Telesis/); });",
  "record_trace": true
}

Optional: connect the local CLI

Configure your MCP client to launch the binary with the mcp argument. Use an absolute executable path so the client does not depend on your shell's PATH.

{
  "mcpServers": {
    "telesis": {
      "command": "/absolute/path/to/telesis",
      "args": [
        "mcp"
      ]
    }
  }
}

Register the local server with Codex

The Codex CLI can register the same local stdio server. Restart or reconnect the client after changing its environment.

codex mcp add telesis -- /absolute/path/to/telesis mcp

Discover the local CLI tools

Start with get_capabilities. For cloud data, call auth_status, authenticate if necessary, and use list_organizations before list_services.

• get_capabilities: local runtime readiness, check types, configured models, and key-presence booleans; no inference requests.
• run_check: local uptime, security, technology, browser, or Playwright execution; inference uses uptime configuration and consumes provider credits.
• security_scan: graded local report with quick, standard, or deep coverage.
• auth_status / auth_login: inspect sign-in or open the browser for a fresh session.
• list_organizations / list_services: discover memberships and inspect a selected organization.
• get_security_trend: read a service's historical security scores.
• get_check / update_playwright_script: read saved configuration and replace a script from a local file while preserving other settings.
• list_check_results / get_check_result: page through persisted history and inspect test evidence.
• get_check_result_artifact: fetch a saved video, trace or screenshot to output_dir, verifying its checksum; returns metadata and a local path.
• trigger_security_scan: enqueue an on-demand cloud security scan for an existing check.

Run a script without embedding its source

Use script_path for a local JavaScript or TypeScript file up to 64 KiB. secret_env accepts names of existing TELESIS_TEST_* variables, never their values. Only use credential injection with trusted scripts. storage_state_path loads a private session file; record_video and record_trace enable bounded recordings. artifacts_dir writes a private local report bundle. Explicit save_to_check uploads the run and recordings to a matching saved check; it requires write access. Saved results contain artifact metadata instead of binary bodies. Authenticated recordings also require allow_sensitive_artifacts=true. Failed Playwright runs set isError=true while retaining structured evidence.

{
  "url": "https://your-service.example",
  "type": "playwright",
  "script_path": "/absolute/path/to/smoke.spec.ts",
  "secret_env": [
    "TELESIS_TEST_EMAIL",
    "TELESIS_TEST_PASSWORD"
  ],
  "timeout_seconds": 60
}

Keep execution scope explicit

The MCP process inherits its own environment, which can differ from a terminal. Configure provider credentials through your client's environment or secret manager and verify with get_capabilities. Do not paste keys into prompts or check configuration.

Cloud quick checks do not run Playwright or use runner inference keys. Scheduled checks require the relevant runner deployment and credentials. The Telesis skill adds operational guidance; installing a skill does not install the CLI binary or Docker runtime.