Summary
Keploy is a network-layer testing tool that uses eBPF to capture real API traffic, database queries, and streaming events, then replays them as tests without code changes. This server gives Claude access to Keploy's test generation and execution capabilities through its remote API. You can generate tests from OpenAPI specs, curl commands, Postman collections, or recorded user traffic, then run those tests with virtualized infrastructure dependencies like Postgres, MongoDB, Kafka, and RabbitMQ. It calculates both traditional code coverage (statement, branch) and API-specific metrics (schema coverage, business flow coverage). Useful when you need to build integration test suites from existing traffic or spec files, especially for polyglot applications where language-agnostic capture matters. The server connects via streamable HTTP to Keploy's cloud API.
Install to Claude Code
verifiedclaude mcp add --transport http mcp https://api.keploy.io/client/v1/mcp --header 'Authorization: YOUR_AUTHORIZATION'Run in your terminal. Add --scope user to make it available in every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Tools
Verified live against the running server on Jun 10, 2026.
verified live80 tools
bulkDeleteTestSuitesPOST /apps/{appId}/test-suites/bulk-delete — Bulk-delete test suites — Requires scope: `write`.2 params
POST /apps/{appId}/test-suites/bulk-delete — Bulk-delete test suites — Requires scope: `write`.
Parameters* required
appId*stringPath parameter: appId
test_suite_ids*arraycreateAPIKeyPOST /api-keys — Create an API key — Requires scope: `admin`. The raw key is returned only once in the response.3 params
POST /api-keys — Create an API key — Requires scope: `admin`. The raw key is returned only once in the response.
Parameters* required
name*stringscopes*arrayttl_daysnumbercreateAppPOST /apps — Create an app — Requires scope: `write`.9 params
POST /apps — Create an app — Requires scope: `write`.
Parameters* required
authobjectAuthentication configuration for test execution. The runner injects the matching headers on every step request.
docsstringFree-form developer docs the AI uses as additional context.
name*stringApp name. IMMUTABLE — cannot be changed via updateApp.
schemastringOpenAPI/Swagger doc the validators use to suggest test cases.
endpointstringwebhook_urlstringOptional webhook URL invoked at run lifecycle events.
api_examplesstringSample request/response pairs the AI consults when authoring suites.
max_test_suitesnumberCap on how many suites generate-tests will mint at once. Server default applies if omitted.
disable_schema_assertionbooleancreateCIBranchPOST /apps/{appId}/branches/ci — Find-or-create a CI branch — Creates a new Keploy branch (or returns the existing one) for a CI pipeline run. Idempotent on the (appId, name) pair. Requires scope: `write`.3 params
POST /apps/{appId}/branches/ci — Find-or-create a CI branch — Creates a new Keploy branch (or returns the existing one) for a CI pipeline run. Idempotent on the (appId, name) pair. Requires scope: `write`.
Parameters* required
name*stringBranch name (e.g., `pr-123`)
appId*stringPath parameter: appId
git_refobjectOptional Git provider context (PR, repo, etc.)
createClusterPOST /clusters — Create a cluster — Provisions a new cluster in the authenticated company and returns its access key. The access key is shown only once. Requires scope: `admin`.2 params
POST /clusters — Create a cluster — Provisions a new cluster in the authenticated company and returns its access key. The access key is shown only once. Requires scope: `admin`.
Parameters* required
name*stringCluster name. Must be unique within the company.
deployment_typestringDefaults to self-hosted when omitted.
createMockPOST /apps/{appId}/recordings/{testSetId}/mocks — Author one mock under a recording — Insert a single mock into the given test set. When `branch_id` is supplied, the mock lands on that branch's overlay (`branch_sandbox_ops`) and only surfaces to main on merge. Without `branch_...5 params
POST /apps/{appId}/recordings/{testSetId}/mocks — Author one mock under a recording — Insert a single mock into the given test set. When `branch_id` is supplied, the mock lands on that branch's overlay (`branch_sandbox_ops`) and only surfaces to main on merge. Without `branch_...
Parameters* required
mockobjectOSS Mock — see schema in keploy.io/server/v3 pkg/models/mock.go. Use only when authoring from typed Go shapes. Lowercase YAML keys are dropped; prefer mock_yaml.
appId*stringPath parameter: appId
branch_idstringOptional branch overlay id. Absent → write lands on main.
mock_yamlstringCanonical single-doc mock YAML (version/kind/name/spec). Preferred over `mock`. Round-trips kind-specific contents losslessly.
testSetId*stringPath parameter: testSetId
createTestSuitePOST /apps/{appId}/test-suites — Create a test suite — Requires scope: `write`.2 params
POST /apps/{appId}/test-suites — Create a test suite — Requires scope: `write`.
Parameters* required
appId*stringPath parameter: appId
branch_idstringOptional Keploy branch UUID. When set, scopes the read/write to that branch's overlay
(copy-on-write — see /apps/{appId}/branches). When absent or empty, operations target
the main branch (the historical default). Required for writes against a branch (the
api-server's branch gate rejects 400 otherwise); reads are tolerant of absence.
create_branchCreate a Keploy branch on an app — find-or-create on name conflict. Pass the dev's CURRENT GIT BRANCH as the name. Detect it BEFORE calling this tool: Bash: `git rev-parse --abbrev-ref HEAD` in the dev's app_dir. Exit non-zero or output "HEAD" → not in a git repo / detached HE...2 params
Create a Keploy branch on an app — find-or-create on name conflict. Pass the dev's CURRENT GIT BRANCH as the name. Detect it BEFORE calling this tool: Bash: `git rev-parse --abbrev-ref HEAD` in the dev's app_dir. Exit non-zero or output "HEAD" → not in a git repo / detached HE...
Parameters* required
name*stringREQUIRED. Pass the dev's current git branch as the name. Detect via Bash `git rev-parse --abbrev-ref HEAD` in app_dir before calling. Don't invent a name — ASK the dev when not in a git repo / detached HEAD.
app_id*stringKeploy app ID
create_mockAuthor a single mock inside a test set. Use this when the dev wants to add a hand-written downstream-call recording (HTTP response, DB result, etc.) without re-running the full record session. Authoring shape — pick ONE: * `mock_yaml` (PREFERRED) — canonical single-doc YAML en...5 params
Author a single mock inside a test set. Use this when the dev wants to add a hand-written downstream-call recording (HTTP response, DB result, etc.) without re-running the full record session. Authoring shape — pick ONE: * `mock_yaml` (PREFERRED) — canonical single-doc YAML en...
Parameters* required
mockobjectOSS Mock typed body — { Name, Kind, Spec }. Optional when mock_yaml is set.
app_id*stringKeploy app ID
branch_id*stringREQUIRED. Keploy branch UUID — resolve via list_branches / create_branch. Direct writes to main are blocked.
mock_yamlstringCanonical single-doc mock YAML (version/kind/name/spec). Preferred over mock — lossless round-trip.
test_set_id*stringTest set id the mock attaches to. Use list_recordings to discover.
create_test_suiteCreate a new API test suite with test steps. Each step defines an HTTP request and assertions to validate the response. Steps can extract values from responses into variables for chaining requests. ═══════════════════════════════════════════════════════════════════ TEMPLATES F...8 params
Create a new API test suite with test steps. Each step defines an HTTP request and assertions to validate the response. Steps can extract values from responses into variables for chaining requests. ═══════════════════════════════════════════════════════════════════ TEMPLATES F...
Parameters* required
name*stringSuite name
app_id*stringKeploy app ID
labelsstringComma-separated labels for filtering
app_dirstringAbsolute path to the dev's repo root (where the app was started). Defaults to '.' (cwd). The CLI invocation cd's here.
app_url*stringBase URL the dev's local app is listening on, e.g. http://localhost:8080. The enterprise CLI hits this when running the suite twice for the idempotency, generator-dynamism, and GET-coupling checks.
branch_id*stringREQUIRED. Keploy branch ID (uuid). Resolve via the explicit two-step flow BEFORE calling: (1) Bash `git rev-parse --abbrev-ref HEAD` in app_dir to detect the dev's git branch; (2) call the create_branch MCP tool with {app_id, name: <git branch>} — find-or-create returns {branch_id, ...}; pass that branch_id here. Direct writes to main are blocked.
steps_json*stringJSON array of test steps
descriptionstringSuite description
deleteAppDELETE /apps/{appId} — Delete an app — Requires scope: `admin`.1 params
DELETE /apps/{appId} — Delete an app — Requires scope: `admin`.
Parameters* required
appId*stringPath parameter: appId
deleteMockDELETE /apps/{appId}/recordings/{testSetId}/mocks/{mockId} — Drop one mock — Idempotent — returns 200 even if the mock is already gone. Path `{mockId}` accepts both the UUID `_id` and the human-readable Name (resolved within the test set). Branch-aware via optional `branch_id`...4 params
DELETE /apps/{appId}/recordings/{testSetId}/mocks/{mockId} — Drop one mock — Idempotent — returns 200 even if the mock is already gone. Path `{mockId}` accepts both the UUID `_id` and the human-readable Name (resolved within the test set). Branch-aware via optional `branch_id`...
Parameters* required
appId*stringPath parameter: appId
mockId*stringMock id (UUID assigned at insert) OR human-readable mock name. The server resolves names within the test set, so the UI can pass either form.
branch_idstringOptional branch overlay id. When set, the delete writes a
tombstone op onto the branch's overlay (main untouched
until the branch merges). When absent, the delete applies
to main directly — no tombstone is involved.
testSetId*stringPath parameter: testSetId
deleteTestSuiteDELETE /apps/{appId}/test-suites/{suiteId} — Delete a test suite — Requires scope: `write`.3 params
DELETE /apps/{appId}/test-suites/{suiteId} — Delete a test suite — Requires scope: `write`.
Parameters* required
appId*stringPath parameter: appId
suiteId*stringPath parameter: suiteId
branch_idstringOptional Keploy branch UUID. When set, scopes the read/write to that branch's overlay
(copy-on-write — see /apps/{appId}/branches). When absent or empty, operations target
the main branch (the historical default). Required for writes against a branch (the
api-server's branch gate rejects 400 otherwise); reads are tolerant of absence.
delete_mockDrop one mock from a test set. Idempotent — returns 200 even if the mock is already gone, so retries on a network blip are safe. Accepts UUID or Name as `mock_id`. `branch_id` is REQUIRED — the delete lays a tombstone overlay on the branch (mergeable). Direct deletes from main...4 params
Drop one mock from a test set. Idempotent — returns 200 even if the mock is already gone, so retries on a network blip are safe. Accepts UUID or Name as `mock_id`. `branch_id` is REQUIRED — the delete lays a tombstone overlay on the branch (mergeable). Direct deletes from main...
Parameters* required
app_id*stringKeploy app ID
mock_id*stringMock UUID OR human-readable Name.
branch_id*stringREQUIRED. Keploy branch UUID. Direct deletes from main are blocked.
test_set_id*stringTest set id
delete_recordingWholesale-delete a recording (test set + its cases + mocks + mapping). `branch_id` is REQUIRED — the delete lays a tombstone overlay on the branch (mergeable). Direct deletes from main via MCP are blocked. Returns { deleted: true } on success, 404 when the (app_id, test_set_id...3 params
Wholesale-delete a recording (test set + its cases + mocks + mapping). `branch_id` is REQUIRED — the delete lays a tombstone overlay on the branch (mergeable). Direct deletes from main via MCP are blocked. Returns { deleted: true } on success, 404 when the (app_id, test_set_id...
Parameters* required
app_id*stringKeploy app ID
branch_id*stringREQUIRED. Keploy branch UUID. Direct deletes from main are blocked.
test_set_id*stringRecording (test set) UUID to delete.
delete_test_suiteDelete a test suite on a Keploy branch — synchronous, no playbook to walk. USE THIS when: * The dev's update_test_suite call was rejected with "preserves no steps from the existing suite — that's a full rewrite, not an edit". Delete the existing suite and re-author from scratc...4 params
Delete a test suite on a Keploy branch — synchronous, no playbook to walk. USE THIS when: * The dev's update_test_suite call was rejected with "preserves no steps from the existing suite — that's a full rewrite, not an edit". Delete the existing suite and re-author from scratc...
Parameters* required
app_id*stringKeploy app ID
reasonstringOptional human-readable reason recorded on the audit event ("AI rewrite", "deprecated endpoint", etc).
suite_id*stringUUID of the test suite to delete
branch_id*stringREQUIRED. Keploy branch UUID. Resolve via the two-step flow: `git rev-parse --abbrev-ref HEAD` → create_branch tool. Direct main writes are blocked.
devloop_begin_oauth_installStart the Path B agent-walked install for the V1 flow. Returns a playbook the AI walks with the dev to land a kep_* PAT in their editor's MCP config. Current implementation routes through app.keploy.io/settings/api-keys (the existing PAT-issuance surface). The full auto-provis...1 params
Start the Path B agent-walked install for the V1 flow. Returns a playbook the AI walks with the dev to land a kep_* PAT in their editor's MCP config. Current implementation routes through app.keploy.io/settings/api-keys (the existing PAT-issuance surface). The full auto-provis...
Parameters* required
editorstringEditor the dev is using (cursor / windsurf / claude-code / claude-desktop / vscode / trae). Tailors the config-path hint in the playbook. Omit if unknown.
devloop_detect_appResolve a Keploy app and return a playbook the AI should walk to inspect the dev's repo for V1 ("user maintains the flow") test generation. This MCP server has no filesystem access — the AI is the inspector. The tool returns: the resolved app metadata (id, name, base_url, stor...3 params
Resolve a Keploy app and return a playbook the AI should walk to inspect the dev's repo for V1 ("user maintains the flow") test generation. This MCP server has no filesystem access — the AI is the inspector. The tool returns: the resolved app metadata (id, name, base_url, stor...
Parameters* required
app_idstringKeploy app UUID (preferred when known)
app_dir*stringAbsolute path to the dev's repo root. Echoed back in the detection_playbook so the AI knows where to grep.
app_name_hintstringCase-insensitive substring of the app name (e.g. the cwd basename). Falls back to app_id when this matches multiple apps.
devloop_expand_coverageExpand V1 API-test coverage from the single seed flow to the remaining detected resources. Use this AFTER devloop_mutation_demo has surfaced a positive catch result for the FIRST resource — that's the "manufactured proof" gate the dev needed before agreeing to scale. Returns a...3 params
Expand V1 API-test coverage from the single seed flow to the remaining detected resources. Use this AFTER devloop_mutation_demo has surfaced a positive catch result for the FIRST resource — that's the "manufactured proof" gate the dev needed before agreeing to scale. Returns a...
Parameters* required
app_id*stringKeploy app UUID
app_dir*stringAbsolute path to the dev's repo root
base_url*stringBase URL the tests run against
devloop_generate_resource_flowGenerate one chained-CRUD API test for a single resource. Behavior depends on the app's devloop_storage_mode (set this first via devloop_resolve_storage / devloop_set_storage_mode): * repo mode → returns a PLAYBOOK for you to walk. Steps: (1) run "keploy test-gen generate-from...5 params
Generate one chained-CRUD API test for a single resource. Behavior depends on the app's devloop_storage_mode (set this first via devloop_resolve_storage / devloop_set_storage_mode): * repo mode → returns a PLAYBOOK for you to walk. Steps: (1) run "keploy test-gen generate-from...
Parameters* required
app_id*stringKeploy app UUID
app_dir*stringAbsolute path to the dev's repo root.
base_url*stringBase URL the test will run against (e.g. http://localhost:8080).
resource*stringThe resource you decided to generate a flow for (e.g. "users", "orders"). Becomes the per-resource subdirectory name.
frameworkstringFramework you detected (express/gin/fastapi/etc.). Used to hint examples in the playbook.
devloop_install_repo_artifactsGenerate the agent-discovery files that let dev #2 onboard via their AI agent without a human pointing at docs. The doc-stated "loop closure" step. Emits THREE files (the AI writes them with its Write tool): * `.claude/skills/keploy/SKILL.md` — Claude Code skill. Has YAML fron...1 params
Generate the agent-discovery files that let dev #2 onboard via their AI agent without a human pointing at docs. The doc-stated "loop closure" step. Emits THREE files (the AI writes them with its Write tool): * `.claude/skills/keploy/SKILL.md` — Claude Code skill. Has YAML fron...
Parameters* required
app_dir*stringAbsolute path to the dev's repo root
devloop_mutation_demoProve the just-generated API test actually catches bugs by applying 3 real source-level mutations to the handler, running the test against each, and reverting. The doc-stated "manufactured proof in the first session" moment. OPT-IN, NOT OPT-OUT — this tool TOUCHES THE DEV'S SO...4 params
Prove the just-generated API test actually catches bugs by applying 3 real source-level mutations to the handler, running the test against each, and reverting. The doc-stated "manufactured proof in the first session" moment. OPT-IN, NOT OPT-OUT — this tool TOUCHES THE DEV'S SO...
Parameters* required
app_id*stringKeploy app UUID
app_dir*stringAbsolute path to the dev's repo root
base_urlstringBase URL the test runs against (e.g. http://localhost:8080). Required so the playbook's `keploy test-gen run` invocation is complete.
resource*stringThe resource name you just generated for (e.g. "users"). Used to build the suite name (<resource>_CRUD) and locate the test YAML.
devloop_record_sandboxRecord mocks for V1 repo-mode API tests using the V1-native CLI command `keploy sandbox local record`. Runs the dev's app under the keploy eBPF agent, drives the V1 chained-CRUD tests from `keploy/api-tests/<resource>/test.yaml`, captures every outbound call (DB queries, Redis...8 params
Record mocks for V1 repo-mode API tests using the V1-native CLI command `keploy sandbox local record`. Runs the dev's app under the keploy eBPF agent, drives the V1 chained-CRUD tests from `keploy/api-tests/<resource>/test.yaml`, captures every outbound call (DB queries, Redis...
Parameters* required
app_id*stringKeploy app UUID (required for cloud uploads; pass empty string + skip-uploads for fully-offline)
app_dir*stringAbsolute path to the service directory (the one whose keploy/api-tests/ holds the V1 tests)
app_url*stringLocalhost URL the dev's app listens on, e.g. http://localhost:8080. The V1 test runner uses this as base-url AND keploy waits for this port to become reachable after spawning the app.
suite_namestringOptional. When set, records only the V1 suite with this name (matches the `name:` field at the top of each test.yaml document). Empty = record every V1 suite under <app_dir>/keploy/api-tests/. Pass this for targeted rerecord; omit for the first full capture.
app_command*stringShell command keploy should spawn to bring the dev's app up under the agent. Examples: `./bin/server` (native), `docker compose -f docker-compose.yml up producer` (docker-compose). For env vars, wrap in a /tmp/*.sh script that exec's the binary — inline `env VAR=… ./binary` does not parse reliably in -c.
container_namestringOnly needed when app_command uses docker / docker-compose. The container instance name keploy should hook into (e.g. orderflow-producer). Read this from the docker-compose.yml's `container_name:` field for the service.
skip_mock_uploadbooleanDon't upload captured mocks to Keploy cloud (local-only). Default false. Set true for fully-offline runs.
skip_report_uploadbooleanDon't upload TestSuiteRun + TestSuiteReport to Keploy cloud. Default false. Set true for fully-offline runs.
devloop_resolve_storageResolve the storage mode for V1 ("user maintains the flow") API tests on this app. ═══════════════════════════════════════════════════════════════════ **MUST BE YOUR FIRST MCP CALL** for ANY of these dev verbs/intents: ══════════════════════════════════════════════════════════...3 params
Resolve the storage mode for V1 ("user maintains the flow") API tests on this app. ═══════════════════════════════════════════════════════════════════ **MUST BE YOUR FIRST MCP CALL** for ANY of these dev verbs/intents: ══════════════════════════════════════════════════════════...
Parameters* required
app_idstringKeploy app UUID. Optional if app_name_hint is set.
app_dirstringAbsolute path to the dev's repo root (used in the hint to check for an existing keploy/api-tests/ directory)
app_name_hintstringCase-insensitive substring of the app name (typically the cwd basename). Optional if app_id is set; one of the two is required.
devloop_scaffold_ciScaffold the GitHub Actions workflow that runs the V1 API tests on every PR. Returns the exact YAML content to write to .github/workflows/keploy.yml + the Bash command to set the KEPLOY_API_KEY secret. The AI walks the playbook with its Write tool + the `gh` CLI. PRECONDITIONS...12 params
Scaffold the GitHub Actions workflow that runs the V1 API tests on every PR. Returns the exact YAML content to write to .github/workflows/keploy.yml + the Bash command to set the KEPLOY_API_KEY secret. The AI walks the playbook with its Write tool + the `gh` CLI. PRECONDITIONS...
Parameters* required
app_id*stringKeploy app UUID
app_dir*stringAbsolute path to the dev's repo root
ci_modestringWhich test surface CI replays. Values: "api-tests" (run V1 source under keploy/api-tests/ against a live app + live deps via `keploy test-gen run`) or "sandbox-replay" (replay the captured sandbox suites under keploy/<SuiteName>/ via `keploy sandbox local replay`; DB/Redis/HTTP downstream calls are served from recorded mocks, app still boots). REQUIRED. The AI MUST inspect <app_dir>/keploy/ first: list subdirs, identify any non-reserved subdir containing a config.yaml (e.g. auth_CRUD, tasks_CRUD, users_CRUD) as a captured sandbox suite. Reserved siblings to ignore: api-tests, reports, schema, keploy.yml, test-set-* (legacy OSS). Routing: only api-tests/ → ci_mode=api-tests; only captured suites → ci_mode=sandbox-replay; BOTH present → YOU MUST ASK THE DEV which (non-negotiable) — surface a clear choice with sandbox-replay marked (Recommended). The asking is non-negotiable when both are present, even if the dev's request already hinted at one mode; confirmation prevents silent misroutes.
app_binarystringPath to the dev's native app binary (or script that spawns it), relative to app_dir. REQUIRED when setup_mode=native — used in the workflow's `keploy sandbox local replay -c "<app_binary>"` boot command. Examples: "./bin/server", "./scripts/run-server.sh". For Go + time_freezing, the workflow builds a SEPARATE faketime binary at <app_binary>.replay (e.g. ./bin/server.replay) — the prod path is never overwritten. NOT used in setup_mode=docker.
go_versionstringGo version to install at /usr/local/go in CI. ONLY honored when setup_mode=native + app_language=go + time_freezing=true. Default 1.22.10. The faketime helper hardcodes /usr/local/go as GOROOT, so the workflow MUST install Go there — not into the toolcache via actions/setup-go. Read the dev's go.mod to pick a matching minor (the Go release archive at https://go.dev/dl/go<version>.linux-amd64.tar.gz is what gets downloaded).
setup_modestringHow the dev's app actually runs in CI. Values: "native" (Go/Node/Python binary or `./bin/server` directly, no Docker for the app — deps may still be in Docker) or "docker" (app boots via `docker compose up <svc>`, with a Dockerfile + compose service). REQUIRED. Pick based on the dev's prior `devloop_record_sandbox` app_command: if it was a binary path or shell script (e.g. `./bin/server`, `./scripts/run-server.sh`, `node index.js`), setup_mode=native. If it was `docker compose up <svc>` or similar, setup_mode=docker. If BOTH are possible (Dockerfile + native binary both exist), YOU MUST ASK THE DEV — don't guess. Native + Docker emit fundamentally different CI workflows (native skips Dockerfile.keploy + compose override entirely; Docker uses them). Cross-wiring (Docker scaffold for a native dev or vice versa) produces a workflow that doesn't match how the dev actually runs the app, and the AI has to improvise — that's the bug this arg fixes.
app_servicestringDocker-compose service name for the dev's app (e.g. 'app', 'producer', 'taskmgr-app'). REQUIRED when setup_mode=docker so the compose override can target the right service for volume mount + ENV. Read from <app_dir>/docker-compose.yml (or the file the dev uses). NOT used in setup_mode=native.
base_branchstringBranch that PRs target (default: main).
app_languagestringPrimary language of the dev's app (go / node / python / java / ruby / other). REQUIRED when time_freezing=true. Determines the time-freezing setup. For Go: needs build-time helper (run `/lib/keploy/go_freeze_time_<arch>` to patch the toolchain) + `-tags=faketime` rebuild — separate binary path in native mode (NEVER overwrite prod), Dockerfile.keploy in docker mode. For non-Go: LD_PRELOAD shim is enough — the Keploy CLI auto-injects it in native mode (zero extra setup beyond `--freezeTime`), or the compose override sets the ENV in docker mode. Detect via repo signals: go.mod → go; package.json → node; requirements.txt|pyproject.toml → python; pom.xml|build.gradle → java; Gemfile → ruby; anything else → other.
compose_filestringCompose file path relative to the repo root. Default: docker-compose.yml. Only honored when setup_mode=docker (the override extends this base file).
time_freezingbooleanWhether the workflow needs Keploy time-freezing (clock-rewinding so recorded JWTs and other time-sensitive tokens validate at replay). Defaults depend on ci_mode: sandbox-replay = true (force-true; non-negotiable, any explicit false is silently overridden), api-tests = false (live deps + current wall-clock means recorded tokens never enter the picture, no benefit). For api-tests, the AI can pass true to pre-stage Dockerfile.keploy + docker-compose.keploy.yml in the repo for a later sandbox-replay switch. For sandbox-replay there is no opt-out — the cost of force-ON for a zero-token app is a dormant volume mount, the cost of force-OFF for a token-bearing app is every PR silently failing 401.
app_startup_delay_secondsnumberSeconds Keploy waits after spawning the app (via `-c`) before sending the first test request. The flag becomes `--delay <N>` on the CLI. Default 10 — covers most Go / Node / Python / typical web apps. Bump for slow-boot frameworks (Spring Boot: 30–60s, Java with large heap: 30s+, anything that runs DB migrations on boot: ~10–20s + migration time). Pass 0 to omit the flag entirely (uses CLI default of 5s). Without enough delay, the first test step gets `connection refused: dial tcp 127.0.0.1:<port>` because the app hasn't bound the port yet.
devloop_schema_drift_reportReport the gap between the app's OpenAPI spec and its V1 API-tests coverage. Reuses the existing schema-coverage endpoint that get_coverage_gaps consumes, but frames the result for V1: which endpoints are uncovered, the recommended order to generate tests for them next (highes...1 params
Report the gap between the app's OpenAPI spec and its V1 API-tests coverage. Reuses the existing schema-coverage endpoint that get_coverage_gaps consumes, but frames the result for V1: which endpoints are uncovered, the recommended order to generate tests for them next (highes...
Parameters* required
app_id*stringKeploy app UUID
devloop_self_healDiagnose a failing V1 API test and propose an action. Triggered when: * keploy test-gen run exited non-zero in a fresh agent session (the dev's code changed since the test was authored). * A PR Keploy comment surfaced a failure and the dev says "fix it". Action classes (mutual...3 params
Diagnose a failing V1 API test and propose an action. Triggered when: * keploy test-gen run exited non-zero in a fresh agent session (the dev's code changed since the test was authored). * A PR Keploy comment surfaced a failure and the dev says "fix it". Action classes (mutual...
Parameters* required
app_dir*stringAbsolute path to the dev's repo root
test_dirstringTest directory to analyse (defaults to <app_dir>/keploy/api-tests)
report_jsonstringPath to a failing test-run JSON report (output of `keploy test-gen run --output json`). The CLI reads failed-step details from this file.
devloop_set_storage_modePersist the V1 storage mode on an app. Call this AFTER devloop_resolve_storage returned source="asked" (the dev gave you a yes/no) or source="inferred" (you confirmed keploy/api-tests/ exists on disk). Switching repo→cloud when local tests exist warns the dev that the existing...3 params
Persist the V1 storage mode on an app. Call this AFTER devloop_resolve_storage returned source="asked" (the dev gave you a yes/no) or source="inferred" (you confirmed keploy/api-tests/ exists on disk). Switching repo→cloud when local tests exist warns the dev that the existing...
Parameters* required
mode*stringStorage mode: "repo" (tests in user's git repo) or "cloud" (tests in Keploy MongoDB). Pass "" to clear.
app_id*stringKeploy app UUID
reasonstringFree-form note recorded with the change (e.g. "asked", "inferred_local_tests_exist", "explicit_switch_with_obsolescence_ack"). Helpful for telemetry; not validated.
devloop_setup_instructionsReturn the V1 "user maintains the flow" install guide — covers Path A (clipboard one-liner), Path B (agent-walked OAuth), and the keploy/api-tests/ on-disk layout V1 creates. Safe to call without authentication; call this when the dev asks 'how do I add Keploy to this repo?' o...
Return the V1 "user maintains the flow" install guide — covers Path A (clipboard one-liner), Path B (agent-walked OAuth), and the keploy/api-tests/ on-disk layout V1 creates. Safe to call without authentication; call this when the dev asks 'how do I add Keploy to this repo?' o...
No parameters — call it with no arguments.
devloop_switch_to_sandboxSwitch the app's V1 CI from "boot the real app + deps" mode to sandbox mode (mocks fetched by content-hash from the cloud canonical pool). The doc-stated trigger: ~1 week after CI is wired, when the dev has felt the slow runs / flakes and you can pitch "your CI takes 90s and f...3 params
Switch the app's V1 CI from "boot the real app + deps" mode to sandbox mode (mocks fetched by content-hash from the cloud canonical pool). The doc-stated trigger: ~1 week after CI is wired, when the dev has felt the slow runs / flakes and you can pitch "your CI takes 90s and f...
Parameters* required
app_id*stringKeploy app UUID
app_dir*stringAbsolute path to the dev's repo root
base_branchstringPR base branch (default: main)
download_recordingDownload a recording — a session of captured API traffic (request/response pairs + outbound mocks) stored as a test_set. Recordings are INPUT artifacts captured by `keploy record`: they're raw traffic that AI generation (generate_and_wait) and manual create_test_suite flows tu...3 params
Download a recording — a session of captured API traffic (request/response pairs + outbound mocks) stored as a test_set. Recordings are INPUT artifacts captured by `keploy record`: they're raw traffic that AI generation (generate_and_wait) and manual create_test_suite flows tu...
Parameters* required
app_id*stringKeploy app ID
test_set_id*stringID of the recording session to download
include_mocksbooleanInclude dependency mocks in the download (default true)
editMockMappingPOST /apps/{appId}/recordings/{testSetId}/test-cases/{testCaseId}/mock-mapping — Link or unlink a mock from a test case — Targeted mutation of the test case's entry in the mapping doc. Add appends a mock entry if not already present; remove drops the entry by name. Both idempo...7 params
POST /apps/{appId}/recordings/{testSetId}/test-cases/{testCaseId}/mock-mapping — Link or unlink a mock from a test case — Targeted mutation of the test case's entry in the mapping doc. Add appends a mock entry if not already present; remove drops the entry by name. Both idempo...
Parameters* required
appId*stringPath parameter: appId
action*stringbranch_idstringmock_kindstringOptional. Stamped on the mapping entry; useful when callers want the kind preserved on the mapping doc for downstream readers.
mock_name*stringtestSetId*stringPath parameter: testSetId
testCaseId*stringTest case name (the mapping doc keys cases by name, not _id).
exportRecordingGET /apps/{appId}/recordings/{testSetId}/export — Export a recording bundle — Export a complete recording bundle: test set metadata, all test cases, mocks, and test-to-mock mappings as a single JSON response. Use ?include_mocks=false to exclude mocks. Requires scope: `read`.3 params
GET /apps/{appId}/recordings/{testSetId}/export — Export a recording bundle — Export a complete recording bundle: test set metadata, all test cases, mocks, and test-to-mock mappings as a single JSON response. Use ?include_mocks=false to exclude mocks. Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
testSetId*stringPath parameter: testSetId
include_mocksbooleanInclude dependency mocks in the export (default true).
generateTestSuitesPOST /apps/{appId}/test-suites/generate — Generate test suites via AI — Requires scope: `write`.13 params
POST /apps/{appId}/test-suites/generate — Generate test suites via AI — Requires scope: `write`.
Parameters* required
authobjectAuthentication configuration for test execution. The runner injects the matching headers on every step request.
docsstringAPI documentation text
appId*stringPath parameter: appId
schemastringOpenAPI spec (YAML or JSON)
timeoutnumberbase_url*stringexamplesstringExample curls or request/response pairs
rate_limitnumberuser_promptstringAdditional instructions for AI generation
webhook_urlstringcode_snippetstringRelevant source code for context
max_test_suitesnumberignore_endpointsarraygenerate_and_waitGenerate test suites from an OpenAPI spec and wait for completion.5 params
Generate test suites from an OpenAPI spec and wait for completion.
Parameters* required
app_id*stringKeploy app ID
schemastringOpenAPI spec (YAML or JSON)
base_url*stringTarget API base URL
user_promptstringInstructions for the AI generator
max_test_suitesnumberMax suites to generate (default 30)
getAppGET /apps/{appId} — Get an app — Requires scope: `read`. Optional `fields` query parameter projects the response to a subset of properties — useful for MCP / AI callers that only need a few identity fields (e.g. `["name","namespace","deployment","origin.clusterName"]`) and don...2 params
GET /apps/{appId} — Get an app — Requires scope: `read`. Optional `fields` query parameter projects the response to a subset of properties — useful for MCP / AI callers that only need a few identity fields (e.g. `["name","namespace","deployment","origin.clusterName"]`) and don...
Parameters* required
appId*stringPath parameter: appId
fieldsstringOptional comma-separated list of response field paths to keep.
Each path is dotted (e.g. `origin.clusterName`). When set, the
response is projected to just those paths inside `data`; the
envelope shape (`{data, meta?}`) is preserved.
getCurrentUserGET /users/me — Get current user — Requires scope: `read`. Returns the user associated with the API key.
GET /users/me — Get current user — Requires scope: `read`. Returns the user associated with the API key.
No parameters — call it with no arguments.
getGeneratedSchemaGET /apps/{appId}/generated-schema — Get auto-generated OpenAPI schema — Returns the OpenAPI schema auto-generated from recorded traffic. Requires scope: `read`.1 params
GET /apps/{appId}/generated-schema — Get auto-generated OpenAPI schema — Returns the OpenAPI schema auto-generated from recorded traffic. Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
getGenerationHistoryDetailsGET /apps/{appId}/generation-history/{jobId} — Get generation history details — Requires scope: `read`.2 params
GET /apps/{appId}/generation-history/{jobId} — Get generation history details — Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
jobId*stringPath parameter: jobId
getJobGET /jobs/{jobId} — Get a job — Requires scope: `read`.1 params
GET /jobs/{jobId} — Get a job — Requires scope: `read`.
Parameters* required
jobId*stringPath parameter: jobId
getLoadTestReportGET /apps/{appId}/load-tests/{runId} — Get a load test report — Requires scope: `read`.2 params
GET /apps/{appId}/load-tests/{runId} — Get a load test report — Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
runId*stringPath parameter: runId
getMockGET /apps/{appId}/recordings/{testSetId}/mocks/{mockId} — Read one mock's canonical YAML — Returns the canonical mock YAML doc (version/kind/name/spec) for the named mock in the given test set. Branch-aware: when `branch_id` is supplied, a branch-only upsert or tombstone takes...4 params
GET /apps/{appId}/recordings/{testSetId}/mocks/{mockId} — Read one mock's canonical YAML — Returns the canonical mock YAML doc (version/kind/name/spec) for the named mock in the given test set. Branch-aware: when `branch_id` is supplied, a branch-only upsert or tombstone takes...
Parameters* required
appId*stringPath parameter: appId
mockId*stringMock id (UUID assigned at insert) OR human-readable mock name. The server resolves names within the test set, so the UI can pass either form.
branch_idstringOptional branch overlay id. Absent → reads from main.
testSetId*stringPath parameter: testSetId
getMockMappingGET /apps/{appId}/recordings/{testSetId}/test-cases/{testCaseId}/mock-mapping — Read the mocks currently linked to a test case — Returns the mock entries in the mapping doc for the named test case. Branch-aware via `branch_id` — when set, the branch overlay's mapping wins over...4 params
GET /apps/{appId}/recordings/{testSetId}/test-cases/{testCaseId}/mock-mapping — Read the mocks currently linked to a test case — Returns the mock entries in the mapping doc for the named test case. Branch-aware via `branch_id` — when set, the branch overlay's mapping wins over...
Parameters* required
appId*stringPath parameter: appId
branch_idstringOptional branch overlay id. Absent → reads from main.
testSetId*stringPath parameter: testSetId
testCaseId*stringTest case name (the mapping doc keys cases by name, not _id).
getRecordingGET /apps/{appId}/recordings/{testSetId} — Get recorded test cases — Returns individual recorded test cases within a test set, including HTTP request/response data. Requires scope: `read`.4 params
GET /apps/{appId}/recordings/{testSetId} — Get recorded test cases — Returns individual recorded test cases within a test set, including HTTP request/response data. Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
testSetId*stringPath parameter: testSetId
getSchemaCoverageGET /apps/{appId}/schema-coverage — Get schema coverage — Requires scope: `read`.1 params
GET /apps/{appId}/schema-coverage — Get schema coverage — Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
getSubscriptionGET /company/subscription — Get company subscription — Requires scope: `read`.
GET /company/subscription — Get company subscription — Requires scope: `read`.
No parameters — call it with no arguments.
getSuiteReportGET /apps/{appId}/test-runs/{runId}/suite-reports/{reportId} — Get a suite report — Requires scope: `read`.3 params
GET /apps/{appId}/test-runs/{runId}/suite-reports/{reportId} — Get a suite report — Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
runId*stringPath parameter: runId
reportId*stringPath parameter: reportId
getTestCaseGET /apps/{appId}/recordings/{testSetId}/test-cases/{testCaseId} — Get a single test case — Returns a single recorded test case identified by its friendly **name** (e.g. `test-4` — the name in the recording yaml) within a recording session. Within `(testSetId, branchId)` the n...4 params
GET /apps/{appId}/recordings/{testSetId}/test-cases/{testCaseId} — Get a single test case — Returns a single recorded test case identified by its friendly **name** (e.g. `test-4` — the name in the recording yaml) within a recording session. Within `(testSetId, branchId)` the n...
Parameters* required
appId*stringPath parameter: appId
branch_idstringOptional Keploy branch UUID. When set, scopes the read/write to that branch's overlay
(copy-on-write — see /apps/{appId}/branches). When absent or empty, operations target
the main branch (the historical default). Required for writes against a branch (the
api-server's branch gate rejects 400 otherwise); reads are tolerant of absence.
testSetId*stringPath parameter: testSetId
testCaseId*stringPath parameter: testCaseId
getTestReportGET /apps/{appId}/test-reports/{reportId} — Get a test run report — Returns the rollup view of a single test run by ID — counts, CI metadata, normalize/coverage data. Cheap and lightweight. For per-test-case diffs and mock mismatches use `getTestReportFull`. Requires scope: `r...2 params
GET /apps/{appId}/test-reports/{reportId} — Get a test run report — Returns the rollup view of a single test run by ID — counts, CI metadata, normalize/coverage data. Cheap and lightweight. For per-test-case diffs and mock mismatches use `getTestReportFull`. Requires scope: `r...
Parameters* required
appId*stringPath parameter: appId
reportId*stringPath parameter: reportId
getTestReportFullGET /apps/{appId}/test-reports/{reportId}/full — Get a fully-inflated test run report — Returns everything about a single legacy /tr test run in one call: the rollup (counts, CI metadata, normalize/coverage data), every test-set report, and — when `include_oss_report=true` (de...7 params
GET /apps/{appId}/test-reports/{reportId}/full — Get a fully-inflated test run report — Returns everything about a single legacy /tr test run in one call: the rollup (counts, CI metadata, normalize/coverage data), every test-set report, and — when `include_oss_report=true` (de...
Parameters* required
appId*stringPath parameter: appId
fieldsstringOptional comma-separated list of response field paths to keep
inside `data`. Supports dotted nested paths and `[].` for
array wildcards (e.g. `failed_steps[].diff`,
`mock_mismatches`). Typical AI use:
`?fields=failed_steps[].diff,mock_mismatches` — projects the
~34k-token full report down to ~5k while preserving the diff
content the model needs to ground its analysis. Omitting
`fields` returns the full report as before.
reportId*stringPath parameter: reportId
failed_onlybooleanWhen `true`, drops every test case whose `status` is not
`FAILED` (passed/skipped/pending/running are elided). Use
this to slim the report down to just the failures the model
needs to analyze — typically 1–5 cases out of 50. Combine
with `fields` for the smallest possible response. Combines
with `mock_mismatches_only` via AND.
include_oss_reportbooleanQuery parameter: include_oss_report
mock_mismatches_onlybooleanQuery parameter: mock_mismatches_only
max_test_cases_per_setnumberQuery parameter: max_test_cases_per_set
getTestRunGET /apps/{appId}/test-runs/{runId} — Get a test run — Requires scope: `read`.2 params
GET /apps/{appId}/test-runs/{runId} — Get a test run — Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
runId*stringPath parameter: runId
getTestSuiteGET /apps/{appId}/test-suites/{suiteId} — Get a test suite — Requires scope: `read`.3 params
GET /apps/{appId}/test-suites/{suiteId} — Get a test suite — Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
suiteId*stringPath parameter: suiteId
branch_idstringOptional Keploy branch UUID. When set, scopes the read/write to that branch's overlay
(copy-on-write — see /apps/{appId}/branches). When absent or empty, operations target
the main branch (the historical default). Required for writes against a branch (the
api-server's branch gate rejects 400 otherwise); reads are tolerant of absence.
getUsageGET /company/usage — Get company usage — Requires scope: `read`.
GET /company/usage — Get company usage — Requires scope: `read`.
No parameters — call it with no arguments.
getValidationResultGET /jobs/{jobId}/validation-result — Get job validation result — Requires scope: `read`.1 params
GET /jobs/{jobId}/validation-result — Get job validation result — Requires scope: `read`.
Parameters* required
jobId*stringPath parameter: jobId
get_app_testing_contextFetch comprehensive context about an app's API plus the canonical test-suite authoring schema. Returns: * app — config, auth shape, appLevelCustomVariables (READ THIS for R32 — your extract keys must not collide with these names) * coverage — API coverage report (which endpoin...1 params
Fetch comprehensive context about an app's API plus the canonical test-suite authoring schema. Returns: * app — config, auth shape, appLevelCustomVariables (READ THIS for R32 — your extract keys must not collide with these names) * coverage — API coverage report (which endpoin...
Parameters* required
app_id*stringKeploy app ID
get_auth_statusCheck whether the current MCP session has a valid-looking Keploy PAT attached. Returns { authenticated, auth_header_present, hint }. Useful as a first step for an agent to decide whether to call other tools or show setup instructions — differentiates 'no header at all' from 'h...
Check whether the current MCP session has a valid-looking Keploy PAT attached. Returns { authenticated, auth_header_present, hint }. Useful as a first step for an agent to decide whether to call other tools or show setup instructions — differentiates 'no header at all' from 'h...
No parameters — call it with no arguments.
get_coverage_gapsGet API coverage and prioritized suggestions for uncovered endpoints.1 params
Get API coverage and prioritized suggestions for uncovered endpoints.
Parameters* required
app_id*stringKeploy app ID
get_session_reportFetch the report for a completed run. ONE tool, THREE report kinds — the response's top-level `kind` field discriminates which kind it is (rerecord / sandbox_run / test_suite_run) and which question the report answers (see core glossary's "three reports"). Read `kind` first, t...3 params
Fetch the report for a completed run. ONE tool, THREE report kinds — the response's top-level `kind` field discriminates which kind it is (rerecord / sandbox_run / test_suite_run) and which question the report answers (see core glossary's "three reports"). Read `kind` first, t...
Parameters* required
app_id*stringKeploy app ID
verbosebooleanForce detailed per-step diagnostics even when all steps passed. Default false. Set true for explain/analyse intents so the dev sees the full picture, not just a one-line summary.
test_run_id*stringTest run ID. Extracted from data.test_run_id on the phase=done NDJSON event written to the progress_file by the headless sandbox CLI.
get_setup_instructionsReturn step-by-step instructions for connecting this MCP server to Cursor, Windsurf, VS Code, Claude Desktop, Claude Code, or Trae. Safe to call without authentication — use this when the user asks 'how do I set up Keploy MCP?' or when a tool call fails with an auth error.
Return step-by-step instructions for connecting this MCP server to Cursor, Windsurf, VS Code, Claude Desktop, Claude Code, or Trae. Safe to call without authentication — use this when the user asks 'how do I set up Keploy MCP?' or when a tool call fails with an auth error.
No parameters — call it with no arguments.
importRecordingPOST /apps/{appId}/recordings/{testSetId}/import — Import test case changes into a recording — Bulk import test case changes: update existing test cases (by ID), insert new ones (without ID), and delete specified test cases. Pass `branch_id` (query or body) to scope the import...5 params
POST /apps/{appId}/recordings/{testSetId}/import — Import test case changes into a recording — Bulk import test case changes: update existing test cases (by ID), insert new ones (without ID), and delete specified test cases. Pass `branch_id` (query or body) to scope the import...
Parameters* required
appId*stringPath parameter: appId
branch_idstringOptional branch overlay id (body alternative to the query param). Either form is accepted; query wins.
testSetId*stringPath parameter: testSetId
test_casesarraydelete_test_case_idsarrayIDs of test cases to delete
listAPIKeysGET /api-keys — List API keys — Requires scope: `admin`.
GET /api-keys — List API keys — Requires scope: `admin`.
No parameters — call it with no arguments.
listAppsGET /apps — List apps — Returns the tenant's apps. Use the optional `q` query parameter to name-filter (case-insensitive substring, e.g. `?q=orderflow` → apps whose name contains 'orderflow'); without it the full paginated list is returned. Callers that know the app's folder /...3 params
GET /apps — List apps — Returns the tenant's apps. Use the optional `q` query parameter to name-filter (case-insensitive substring, e.g. `?q=orderflow` → apps whose name contains 'orderflow'); without it the full paginated list is returned. Callers that know the app's folder /...
Parameters* required
qstringCase-insensitive substring to filter app names by. Omit to list all apps.
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
listAppsByClusterGET /apps/by-cluster/{clusterId} — List apps in a cluster — Returns apps belonging to a specific cluster. More efficient than iterating all apps. Requires scope: `read`.1 params
GET /apps/by-cluster/{clusterId} — List apps in a cluster — Returns apps belonging to a specific cluster. More efficient than iterating all apps. Requires scope: `read`.
Parameters* required
clusterId*stringPath parameter: clusterId
listAppsWithRecordingsGET /apps/with-recordings — List proxy apps with network recordings — Returns all k8s-proxy apps (origin.type=PROXY). These apps are auto-created by the Keploy k8s-proxy agent on first recording and contain network recordings of ingress HTTP traffic (as Keploy test cases) and...
GET /apps/with-recordings — List proxy apps with network recordings — Returns all k8s-proxy apps (origin.type=PROXY). These apps are auto-created by the Keploy k8s-proxy agent on first recording and contain network recordings of ingress HTTP traffic (as Keploy test cases) and...
No parameters — call it with no arguments.
listBranchesGET /apps/{appId}/branches — List Keploy branches on an app — Returns every Keploy branch on an app, optionally filtered by status. Used by MCP write tools and CI integrations to enumerate branches without shelling out to the CLI. Requires scope: `read`.2 params
GET /apps/{appId}/branches — List Keploy branches on an app — Returns every Keploy branch on an app, optionally filtered by status. Used by MCP write tools and CI integrations to enumerate branches without shelling out to the CLI. Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
statusstringOptional status filter. Omit to return all branches. (allowed values: open|review_requested|approved|changes_requested|merged|closed|conflict — CASE-SENSITIVE)one of
open · review_requested · approved · changes_requested · merged · closedlistClustersGET /clusters — List clusters — Returns all clusters for the authenticated company. Requires scope: `read`.
GET /clusters — List clusters — Returns all clusters for the authenticated company. Requires scope: `read`.
No parameters — call it with no arguments.
listGenerationHistoryGET /apps/{appId}/generation-history — List generation history — Requires scope: `read`. Returns all entries (no pagination).1 params
GET /apps/{appId}/generation-history — List generation history — Requires scope: `read`. Returns all entries (no pagination).
Parameters* required
appId*stringPath parameter: appId
listJobsGET /jobs — List jobs — Requires scope: `read`.2 params
GET /jobs — List jobs — Requires scope: `read`.
Parameters* required
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
listLoadTestRunsGET /apps/{appId}/load-tests — List load test runs — Requires scope: `read`. Returns all runs (no pagination).1 params
GET /apps/{appId}/load-tests — List load test runs — Requires scope: `read`. Returns all runs (no pagination).
Parameters* required
appId*stringPath parameter: appId
listMocksGET /apps/{appId}/recordings/{testSetId}/mocks — List mocks for a recording — Returns mock reference metadata and optionally parsed mock specs for a test set. Use ?include_specs=true to download and parse the actual mock YAML from object storage. Pass `branch_id` to scope the...4 params
GET /apps/{appId}/recordings/{testSetId}/mocks — List mocks for a recording — Returns mock reference metadata and optionally parsed mock specs for a test set. Use ?include_specs=true to download and parse the actual mock YAML from object storage. Pass `branch_id` to scope the...
Parameters* required
appId*stringPath parameter: appId
branch_idstringOptional Keploy branch UUID. When set, scopes the read/write to that branch's overlay
(copy-on-write — see /apps/{appId}/branches). When absent or empty, operations target
the main branch (the historical default). Required for writes against a branch (the
api-server's branch gate rejects 400 otherwise); reads are tolerant of absence.
testSetId*stringPath parameter: testSetId
include_specsbooleanWhen true, download and parse the actual mock YAML specs from object storage.
listRecordingsGET /apps/{appId}/recordings — List recording sessions — Returns test sets (recording sessions) for an app. Requires scope: `read`.3 params
GET /apps/{appId}/recordings — List recording sessions — Returns test sets (recording sessions) for an app. Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
listSuiteReportsGET /apps/{appId}/test-runs/{runId}/suite-reports — List suite reports for a test run — Requires scope: `read`. Supports cursor-based pagination.5 params
GET /apps/{appId}/test-runs/{runId}/suite-reports — List suite reports for a test run — Requires scope: `read`. Supports cursor-based pagination.
Parameters* required
afterstringCursor for forward pagination
appId*stringPath parameter: appId
runId*stringPath parameter: runId
beforestringCursor for backward pagination
page_sizenumberNumber of items per page
listTestCaseReportsGET /apps/{appId}/test-reports/{reportId}/test-set-reports/{testSetReportId}/test-cases — List test case reports — Returns individual test case results with expected/actual diffs within a test set report. Requires scope: `read`.5 params
GET /apps/{appId}/test-reports/{reportId}/test-set-reports/{testSetReportId}/test-cases — List test case reports — Returns individual test case results with expected/actual diffs within a test set report. Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
reportId*stringPath parameter: reportId
testSetReportId*stringPath parameter: testSetReportId
listTestReportsGET /apps/{appId}/test-reports — List test run reports — Browse legacy /tr test runs for an app. Combine `status` + `source` to scope to specific run kinds — e.g. `status=FAILED` + `source=ci` shows broken CI runs only. Use `branch_id` to scope to a Keploy branch overlay. Use...8 params
GET /apps/{appId}/test-reports — List test run reports — Browse legacy /tr test runs for an app. Combine `status` + `source` to scope to specific run kinds — e.g. `status=FAILED` + `source=ci` shows broken CI runs only. Use `branch_id` to scope to a Keploy branch overlay. Use...
Parameters* required
appId*stringPath parameter: appId
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
sincenumberQuery parameter: since
untilnumberQuery parameter: until
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
sourcestringQuery parameter: source (allowed values: ci|manual — CASE-SENSITIVE)one of
ci · manualstatusstringQuery parameter: status (allowed values: PASSED|FAILED|RUNNING|PENDING|IGNORED|OBSOLETE — CASE-SENSITIVE)one of
PASSED · FAILED · RUNNING · PENDING · IGNORED · OBSOLETEbranch_idstringQuery parameter: branch_id
listTestRunsGET /apps/{appId}/test-runs — List test runs — List test runs for an app. Optional `kind` query param filters by run kind: `rerecord` (record_sandbox_test runs), `sandbox_run` (replay_sandbox_test runs), or `test_suite_run` (replay_test_suite live runs). Omit to return runs of...4 params
GET /apps/{appId}/test-runs — List test runs — List test runs for an app. Optional `kind` query param filters by run kind: `rerecord` (record_sandbox_test runs), `sandbox_run` (replay_sandbox_test runs), or `test_suite_run` (replay_test_suite live runs). Omit to return runs of...
Parameters* required
kindstringFilter by run kind. Omit to return runs of every kind. (allowed values: rerecord|sandbox_run|test_suite_run — CASE-SENSITIVE)one of
rerecord · sandbox_run · test_suite_runappId*stringPath parameter: appId
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
listTestSetReportsGET /apps/{appId}/test-reports/{reportId}/test-set-reports — List test set reports within a run — Returns per-test-set results within a test run report. Requires scope: `read`.4 params
GET /apps/{appId}/test-reports/{reportId}/test-set-reports — List test set reports within a run — Returns per-test-set results within a test run report. Requires scope: `read`.
Parameters* required
appId*stringPath parameter: appId
limitnumberPage size. Defaults to 20 when omitted; `limit=0` is also treated
as "use default" (so existing clients sending an explicit zero
keep the prior behaviour). Capped at 100 — the spec rejects
higher values with 400 so callers fail loudly instead of being
silently clamped, and the handler enforces the same cap as a
defence-in-depth fallback.
offsetnumberZero-based pagination offset. Negative values are rejected — the
handler also clamps to 0 as a defence-in-depth fallback.
reportId*stringPath parameter: reportId
listTestSuitesGET /apps/{appId}/test-suites — List test suites — List test suites for an app. Optional `has_sandbox_test` query param filters by sandbox-test linkage: `true` returns only suites that have a sandbox test (linked=true / test_set_id populated); `false` returns only suites witho...7 params
GET /apps/{appId}/test-suites — List test suites — List test suites for an app. Optional `has_sandbox_test` query param filters by sandbox-test linkage: `true` returns only suites that have a sandbox test (linked=true / test_set_id populated); `false` returns only suites witho...
Parameters* required
qstringSubstring / regex match on suite name (server-side regex filter). Use for bounded duplicate-checks on large apps so MCP doesn't have to paginate the whole list.
afterstringCursor for forward pagination (mutually exclusive with `before`)
appId*stringPath parameter: appId
beforestringCursor for backward pagination (mutually exclusive with `after`)
branch_idstringOptional Keploy branch UUID. When set, scopes the read/write to that branch's overlay
(copy-on-write — see /apps/{appId}/branches). When absent or empty, operations target
the main branch (the historical default). Required for writes against a branch (the
api-server's branch gate rejects 400 otherwise); reads are tolerant of absence.
page_sizenumberNumber of items per page
has_sandbox_teststringFilter by sandbox-test linkage. Omit to return every suite. (allowed values: true|false — CASE-SENSITIVE)one of
true · falselist_branchesList Keploy branches on an app. Use this BEFORE any write tool (create_test_suite, update_test_suite, sandbox flows) to see if a branch already exists for the dev's current work. If one matches the dev's git branch, pass its branch_id (or branch_name) to the write tool. Otherw...2 params
List Keploy branches on an app. Use this BEFORE any write tool (create_test_suite, update_test_suite, sandbox flows) to see if a branch already exists for the dev's current work. If one matches the dev's git branch, pass its branch_id (or branch_name) to the write tool. Otherw...
Parameters* required
app_id*stringKeploy app ID
statusstringoptional status filter — open / review_requested / approved / changes_requested / merged / closed / conflict
normalizeSuiteReportPOST /apps/{appId}/test-runs/{runId}/suite-reports/{reportId}/normalize — Normalize a suite report — Requires scope: `write`.3 params
POST /apps/{appId}/test-runs/{runId}/suite-reports/{reportId}/normalize — Normalize a suite report — Requires scope: `write`.
Parameters* required
appId*stringPath parameter: appId
runId*stringPath parameter: runId
reportId*stringPath parameter: reportId
normalizeTestRunPOST /apps/{appId}/test-runs/{runId}/normalize — Normalize a test run — Requires scope: `write`.2 params
POST /apps/{appId}/test-runs/{runId}/normalize — Normalize a test run — Requires scope: `write`.
Parameters* required
appId*stringPath parameter: appId
runId*stringPath parameter: runId
⚡️ API tests faster than unit tests, from user traffic ⚡️
🌟 The must-have tool for developers in the AI-Gen era for 90% test coverage 🌟
Keploy is a developer‑centric API and integration testing tool that auto‑generates tests and data‑mocks faster than unit tests.
It records API calls, database queries, and streaming events — then replays them as tests. Under the hood, Keploy uses eBPF to capture traffic at the network layer, but for you it’s completely code‑less and language‑agnostic.
🐰 Fun fact: Keploy uses itself for testing! Check out our swanky coverage badge:
Key Highlights
🎯 No code changes
Just run your app with keploy record. Real API + integration flows are automatically captured as tests and mocks. (Keploy uses eBPF under the hood to capture traffic, so you don’t need to add any SDKs or modify code.)
📹 Record and Replay complex Flows
Keploy can record and replay complex, distributed API flows as mocks and stubs. It's like having a very light-weight time machine for your tests—saving you tons of time!
👉 Read the docs on record-replay
🐇 Complete Infra‑Virtualization (beyond HTTP mocks)
Unlike tools that only mock HTTP endpoints, Keploy records databases (Postgres, MySQL, MongoDB), streaming/queues (Kafka, RabbitMQ), external APIs, and more.
It replays them deterministically so you can run tests without re‑provisioning infra.
👉 Read the docs on infra virtualisation
🧪 Combined Test Coverage
If you’re a developer, you probably care about statement and branch coverage — Keploy calculates that for you.
If you’re a QA, you focus more on API schema and business use‑case coverage — Keploy calculates that too. This way coverage isn’t subjective anymore.
🤖 Expand API Coverage using AI
Keploy uses existing recordings, Swagger/OpenAPI Schema to find: boundary values, missing/extra fields, wrong types, out‑of‑order sequences, retries/timeouts.
This helps expand API Schema, Statement, and Branch Coverage.
Other Capabilities
-
🌐 CI/CD Integration: Run tests with mocks anywhere you like—locally on the CLI, in your CI pipeline (Jenkins, Github Actions..) , or even across a Kubernetes cluster. Read more
-
🎭 Multi-Purpose Mocks: You can also use Keploy-generated Mocks, as server Tests!
-
📊 Reporting: Unified reports for API, integration, unit, and e2e coverage with insights directly in your CI or PRs.
-
🖥️ Console: A developer-friendly console to view, manage, and debug recorded tests and mocks.
-
⏱️ Time Freezing: Deterministically replay tests by freezing system time during execution. Read more
-
📚 Mock Registry: Centralized registry to manage, reuse, and version mocks across teams and environments. Read more
Quick Start
1. Install Keploy Agent
curl --silent -O -L https://keploy.io/install.sh && source install.sh
2. Record Test Cases
Start your app under Keploy to convert real API calls into tests and mocks.
keploy record -c "CMD_TO_RUN_APP"
Example for Python:
keploy record -c "python main.py"
3. Run Tests
Run tests offline without external dependencies.
keploy test -c "CMD_TO_RUN_APP" --delay 10
Resources
- 📘 Installation
- 🏁 QuickStarts
Languages & Frameworks (Any stack)
Because Keploy intercepts at the network layer (eBPF), it works with any language, framework, or runtime—no SDK required.
Note: Some of the dependencies are not open-source by nature because their protocols and parsings are not open-sourced. It's not supported in Keploy enterprise.
Questions?
Book a Live Demo / Enterprise Support
Want a guided walkthrough, dedicated support, or help planning enterprise rollout?
Prefer a calendar invite? Mention your availability in the email—we’ll send a calendar invite right away.
Documentation & Community
- 📘 Documentation — Explore the full docs
- 💬 Slack Community — Join the conversation
- 📜 Contribution Guidelines
- ❤️ Code of Conduct
- 📢 Blog — Read articles and updates
Contribute & Collaborate
Whether you're new or experienced, your input matters. Help us improve Keploy by contributing code, reporting issues, or sharing feedback.
Together, let's build better testing tools for modern applications.
Featured
Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →