Skip to main content

UI Testing MCP tools reference​

View as Markdown
FreeTeamsScaleEnterpriseSelf-HostedDedicated

The Keploy MCP server gives an AI agent every step of UI capture as a tool: create an app, mint an ingest key, check that recordings arrive, and read flows, journeys and test runs. Each UI capture tool is generated from the REST API operation of the same name, so it takes the same inputs and returns the same answer.

The server​

WhatValue
URLhttps://api.keploy.io/client/v1/mcp. When you self-host, your API server's URL followed by /client/v1/mcp.
TransportStreamable HTTP, stateless.
Server namekeploy-atg
AuthenticationAn OAuth sign-in, or a Keploy API key in Authorization: Bearer kep_... or X-API-Key: kep_.... See OAuth or API key.
Rate limitEach tool call that reaches the API counts against the key's 100 requests a minute, as a REST call does.

Tool-search mode. The server's tools/list shows seven tools, so that the full catalogue does not fill the agent's context: the meta-tools search_tools, get_tool_schema and invoke_tool, and the sign-in and setup tools get_auth_status, get_setup_instructions, devloop_setup_instructions and devloop_begin_oauth_install. Every other tool is still there:

  • get_tool_schema({names: [...]}) returns the description and input schema of each tool you name. Ask for all you need in one call: the names are in the table below and in the server's instructions.
  • search_tools({query}) finds tools by keyword and returns each match's name and a one-line summary, not its schema. It ranks the whole catalogue by keyword and returns 10 matches unless you pass limit, so a query such as "ui capture" can return API testing tools too and leave some UI capture tools out. Fetch tools whose names you know with get_tool_schema.
  • invoke_tool({name, arguments}) runs a tool by name. A tool missing from tools/list can also be called directly with tools/call and its exact name.

Instructions. The server's initialize answer carries instructions with a UI CAPTURE section: the order of the tools below, the wait before a visit becomes flows, and that the replay runner is not in a release build yet, so an agent should not tell you to run it.

Tools​

Every UI capture tool takes appId, the app's ID. The scope is the API key's; the permission is what the key's owner must hold on the app.

ToolWhat it doesInputsScope and permission
createAppCreates an app. An app for UI capture needs only a name, which cannot be changed later.name (required), and other optional app settingswrite
listAppsLists the company's apps; q filters by name.q, offset, limitread
getAppReturns one app.appId, fieldsread
deleteAppDeletes an app.appIdadmin
uiCaptureSetupMints an ingest key and returns it once, with the endpoint, the SDK install command and an init snippet.appId, name, ttlDayswrite, testgen:run
listUIIngestKeysLists the app's ingest keys, revoked ones included, never their secrets.appIdread, app:view
revokeUIIngestKeyRevokes one ingest key.appId, keyIdwrite, testgen:run
uiCaptureStatusSays whether recordings arrive and have become flows, as a state with what to do next.appIdread, app:view
listUIFlowsLists the app's flows.appId, limit, offset, statusread, app:view
getUIFlowReturns one flow's steps, network calls and end state.appId, flowIdread, app:view
uiFlowGraphHow the app's visits move between pages.appIdread, app:view
uiJourneysThe journey plan: the journeys sessions take, each with its share of sessions.appId, refreshread, app:view; refresh: true also needs write and testgen:run
uiJourneyImpactThe share of sessions that took at least one of a set of the plan's journeys.appId, planId (required), journeyIds (required)read, app:view
listUITestRunsLists the app's UI test runs, newest first, one summary line each.appId, offset, limitread, app:view
getUITestRunReturns one UI test run with each journey's verdict.appId, runIdread, app:view

The REST API reference describes each tool's answer in full. A UI test run today comes only from a flow page's Generate Test in the dashboard, and it stays pending: no tool creates or runs one, and the runner that replays journeys is not in a release build yet.

Call a tool​

An MCP client makes these calls for your agent. To see one by hand, send JSON-RPC to the server:

curl https://api.keploy.io/client/v1/mcp \
-H "Authorization: Bearer kep_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "invoke_tool",
"arguments": {"name": "uiCaptureStatus", "arguments": {"appId": "<appId>"}}
}
}'

The tool's answer is one text item: the REST API's JSON answer, with the HTTP status added as status_code. A refusal sets the result's isError, and its text carries the API's error, as here for getUITestRun with a run that does not exist:

{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "UI test run not found"
},
"meta": {
"timestamp": "2026-11-20T07:28:18Z"
},
"status_code": 404
}

Input types​

A REST operation's path and query parameters become string, number or boolean inputs, and its request body's fields keep their types. Two cases to know:

  • journeyIds is one string, the journey IDs joined with commas: "journeyIds": "a1b2…,c3d4…". It takes 1 to 100 IDs, each one of the plan's journeys.
  • refresh is a boolean: "refresh": true.

OAuth or API key​

  • OAuth. A request with no credential is answered 401 with a WWW-Authenticate challenge that names the server's OAuth metadata, and an MCP client that supports OAuth signs in from it: you approve the sign-in in your browser. The token it gets has the read and write scopes, never admin, so it cannot call deleteApp. It works only through the MCP server, not on the REST API.
  • An API key. A personal access token from Settings → API Keys in the dashboard, or the one keploy mcp-install mints, in Authorization: Bearer kep_.... Give it the read and write scopes to set up capture; deleting an app needs admin, which only organization admins can give a token.
  • A service-account key bound to the UI_READER role on an app reads that app's capture status, flows, flow graph, journeys, impact and test runs. It cannot create or delete apps, list ingest keys, or mint or revoke them. On the Free plan a service account can hold only MOCK_READER, so this needs a paid plan.

An ingest key is not accepted: it can only post recordings.