MCP

Smoketest exposes a remote MCP server at:

https://api.smoketest.sh/mcp

Use it from MCP-capable clients to inspect your Smoketest workspace, list projects and reusable Tests, update non-secret project and Test fields, and trigger or cancel Runs. Jira and Linear Connections, Test Sources, Test Requests, and generated Tests are intentionally unavailable through MCP in this release.

Quickstart: Claude custom connector

Claude can connect directly to Smoketest with web sign-in.

1. In Claude, open Settings -> Connectors -> Add custom connector.

2. Enter the MCP URL:

   https://api.smoketest.sh/mcp

3. Click Connect.

4. Sign in to Smoketest in the browser window Claude opens.

5. Review the requested scopes and approve the connection.

You do not need to enter an OAuth Client ID or Client Secret for the standard Claude custom connector setup. Smoketest supports dynamic client registration and public authorization-code OAuth with PKCE.

If Claude asks for scopes and does not prefill them, start with read. Add run only when Claude should trigger tests, and add write only when Claude should create or update non-secret project and test fields.

Approved MCP access tokens expire after 90 days. OAuth clients that request refresh-token support can rotate their token through Smoketest. You can revoke access any time from Workspace Settings -> API Keys.

What Happens During Sign-In

Smoketest redirects you to a web approval screen that shows:

• the MCP client name
• your active Smoketest workspace
• the requested scopes
• the redirect destination
• a warning when run or write is requested

Approving creates a smkt_ API key named Smoketest MCP - <client>. The key is source-marked as mcp, limited to the approved scopes and your current organization role, and can only be used against /mcp.

If a client requests no scopes, Smoketest defaults to read.

Scopes

Prefer the smallest scope set your client needs.

Claude Desktop With a Local Proxy

If you configure Claude Desktop through claude_desktop_config.json, use the advanced manual token setup below, then pass the token through mcp-remote.

macOS config path:

~/Library/Application Support/Claude/claude_desktop_config.json

Example:

{
  "mcpServers": {
    "smoketest": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.smoketest.sh/mcp",
        "--header",
        "Authorization: Bearer ${SMOKETEST_MCP_TOKEN}"
      ],
      "env": {
        "SMOKETEST_MCP_TOKEN": "smkt_..."
      }
    }
  }
}

Restart Claude Desktop after editing the config. Then open a chat, use the connectors/tools menu, and enable Smoketest.

Claude Code

Claude Code can add remote HTTP MCP servers directly. Create a manual token first, then run:

claude mcp add --transport http smoketest https://api.smoketest.sh/mcp \
  --header "Authorization: Bearer $SMOKETEST_MCP_TOKEN"

Inside Claude Code, run:

/mcp

Use the MCP panel to verify that Smoketest connected and to inspect available tools.

Codex

Codex reads MCP configuration from ~/.codex/config.toml and project .codex/config.toml files. For a personal setup, create a manual token first, then add:

[mcp_servers.smoketest]
url = "https://api.smoketest.sh/mcp"
bearer_token_env_var = "SMOKETEST_MCP_TOKEN"

Export the token before starting Codex:

export SMOKETEST_MCP_TOKEN="smkt_..."

For a repo-shared config, keep bearer_token_env_var but do not commit the token itself. Each user should create their own MCP token and set the environment variable locally.

Cursor

In Cursor, open Cursor Settings -> Tools & MCP -> New MCP Server, then add Smoketest as a remote HTTP server.

If Cursor opens mcp.json, use:

{
  "mcpServers": {
    "smoketest": {
      "type": "http",
      "url": "https://api.smoketest.sh/mcp",
      "headers": {
        "Authorization": "Bearer smkt_..."
      }
    }
  }
}

Prefer user-level MCP settings for personal tokens. Do not commit a project .cursor/mcp.json containing a real token. If your Cursor version supports environment interpolation in HTTP headers, store the token in an environment variable instead of writing the raw token into JSON.

Generic MCP Clients

Clients that support OAuth authorization-code with PKCE can discover Smoketest OAuth metadata:

https://api.smoketest.sh/.well-known/oauth-protected-resource/mcp
https://api.smoketest.sh/.well-known/oauth-authorization-server

Supported OAuth features:

• dynamic client registration at POST /oauth/register
• authorization-code + PKCE at GET /oauth/authorize
• device authorization at POST /oauth/device/code
• token exchange at POST /oauth/token
• refresh-token rotation at POST /oauth/token
• token revocation at POST /oauth/revoke

Clients that only support static bearer tokens can use:

{
  "type": "http",
  "url": "https://api.smoketest.sh/mcp",
  "headers": {
    "Authorization": "Bearer smkt_..."
  }
}

Advanced: Manual Token Setup

Use this test for Claude Desktop local proxy, Claude Code, Codex, Cursor, CLI scripts, and MCP clients that do not support web OAuth yet.

1. Register a Client

CLIENT_ID=$(
  curl -s -X POST https://api.smoketest.sh/oauth/register \
    -H "content-type: application/json" \
    -d '{"client_name":"My MCP client","scope":"read run"}' \
  | jq -r .client_id
)

echo "$CLIENT_ID"

Choose only the scopes your client needs:

• read for inspection
• read run for triggering tests
• read write run only when the client should edit projects or tests

If you omit scope, Smoketest grants read only.

2. Start Device Authorization

DEVICE=$(
  curl -s -X POST https://api.smoketest.sh/oauth/device/code \
    -H "content-type: application/x-www-form-urlencoded" \
    --data-urlencode "client_id=$CLIENT_ID" \
    --data-urlencode "scope=read run"
)

echo "$DEVICE" | jq

Open the verification_uri_complete URL from the response, sign in to Smoketest, review the requested scopes, and approve the connection.

3. Exchange the Device Code

SMOKETEST_MCP_TOKEN=$(
  curl -s -X POST https://api.smoketest.sh/oauth/token \
    -H "content-type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
    --data-urlencode "client_id=$CLIENT_ID" \
    --data-urlencode "device_code=$(echo "$DEVICE" | jq -r .device_code)" \
  | jq -r .access_token
)

echo "$SMOKETEST_MCP_TOKEN"

Store the token somewhere private, such as a password manager, local environment variable, or the secure credential storage your MCP client provides. Do not commit it to a repository.

Available Tools

Read Tools

Require read.

Write Tools

Require write and confirm: true.

Tagging Tests

Pass tags as an array of project tag names when creating a test. Existing tags are reused case-insensitively, and missing tags are created:

{
  "projectId": "5f4bb4fc-95c6-4fc2-864f-56f4379cf4d7",
  "name": "Checkout",
  "description": "User completes checkout",
  "url": "https://example.com/checkout",
  "tags": ["critical", "checkout"],
  "confirm": true
}

On update_test, tags is the complete desired tag list. Passing an empty array removes every tag; omitting tags leaves the current tags unchanged. A single write can assign up to 25 tags, with each name limited to 64 characters.

Scheduling Tests

Set trigger to schedule, provide a supported schedule preset, and optionally provide an IANA timezone. Daily and weekly preset hours are interpreted in scheduleTimezone; when omitted, the timezone defaults to UTC.

{
  "projectId": "5f4bb4fc-95c6-4fc2-864f-56f4379cf4d7",
  "name": "Daily checkout",
  "description": "User completes checkout",
  "url": "https://example.com/checkout",
  "trigger": "schedule",
  "schedule": "daily-9",
  "scheduleTimezone": "Europe/Berlin",
  "confirm": true
}

Supported presets:

• Hourly: hourly-1, hourly-3, hourly-6, hourly-12
• Daily: daily-{hour}, where hour is 0, 6, 9, 12, 15, 18, or 22
• Weekly: weekly-{day}-{hour}, where day is 0 (Sunday) through 6 (Saturday), and hour uses the daily values above

The same trigger, schedule, and scheduleTimezone fields work with update_test. Setting trigger back to on_demand or api removes the active schedule.

Run Tools

Require run and confirm: true.

Confirmation

All write and run tools require explicit confirmation:

{
  "testId": "9b8ab084-7121-42a5-b13c-9ba3d4b3355c",
  "confirm": true
}

Without confirm: true, Smoketest returns:

{
  "error": "confirmation_required"
}

and does not change resources or spend credits.

Guardrails and Limits

• MCP tokens use read, write, and run scopes intersected with the creator’s current organization role and project/source assignments. Viewer tokens are read-only. Removing membership or access affects subsequent tool calls. Organization Admin does not grant platform-admin access.
• /mcp accepts only tokens created through Smoketest MCP OAuth.
• MCP-issued tokens are rejected by the normal Smoketest API outside /mcp.
• Write tools exclude deletes, environment secrets, basic-auth passwords, and model overrides. Test writes support preset schedules, not arbitrary cron expressions.
• URLs accepted by MCP tools must be http or https.
• Tag-based run fanout is capped at 25 tests.
• Tool calls are rate limited: 60 MCP requests/min per API key, 20 write tools/min, 10 run tools/min, and 3 tag-run tools/min.
• Smoketest audits every MCP tool call, including denied, failed, rate-limited, and confirmation-blocked calls. Secret-like input fields are redacted before storage.

Revoke Access

Open Workspace Settings -> API Keys and revoke the key named Smoketest MCP - <client>. Revoked and expired MCP tokens stop working immediately for /mcp.

You can also revoke with OAuth token revocation:

curl -X POST https://api.smoketest.sh/oauth/revoke \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "token=$SMOKETEST_MCP_TOKEN"

Client Docs

• Claude custom connectors
• Claude Code MCP
• Codex configuration
• Cursor MCP

Troubleshooting