MCP Tool Reference
This page documents every tool exposed by the Pie MCP server (https://mcp.pie.inc) with structured parameter schemas. Use this reference when building integrations or when your AI coding assistant needs exact tool definitions.
For natural-language usage examples, see Available Functions.
MCP Server: https://mcp.pie.inc
Protocol Version: 2024-11-05
Transport: Streamable HTTP
Authentication: X-API-Key header or api_key query parameter
Issue Management
get_issues
Fetch issues with optional filtering. Returns simplified list by default (IssueID, Title, Description). By default returns only active (open) issues - rejected and resolved/dismissed issues are excluded.
| Parameter | Type | Required | Description |
|---|---|---|---|
| detailed | boolean | No | Set to true for full issue details including resolution status, test case info, steps, and assertions |
| resolution | string | No | Filter by lifecycle state: comma-separated from active, resolved, rejected. Defaults to active. Use active,resolved,rejected to see all |
| triage | string | No | Filter by admin triage: comma-separated from approved, pending |
| testSuiteId | string | No | Filter issues by test suite ID |
| runId | string | No | Filter issues by the run in which they were first discovered |
| cursor | string | No | Pagination cursor. Omit for first page |
get_issue
Fetch details for a single issue by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| issueId | string | Yes | The ID of the issue to fetch |
| detailed | boolean | No | Set to true for full details including test case info, steps, assertions, and comments |
resolve_issues
Close issues as fixed/resolved. Changes resolution state from active to resolved.
| Parameter | Type | Required | Description |
|---|---|---|---|
| issueIds | string[] | Yes | Array of issue IDs to resolve |
| dismissedReason | string | No | Reason for resolving |
reject_issues
Close issues as false positives, or undo a previous rejection.
| Parameter | Type | Required | Description |
|---|---|---|---|
| issueIds | string[] | Yes | Array of issue IDs to reject (or un-reject if undo=true) |
| rejectReason | string | No | Reason for rejecting (ignored when undo=true) |
| undo | boolean | No | Set to true to reverse a previous rejection back to pending |
approve_issues
Confirm issues as valid (triage), or undo a previous approval.
| Parameter | Type | Required | Description |
|---|---|---|---|
| issueIds | string[] | Yes | Array of issue IDs to approve (or unapprove if undo=true) |
| undo | boolean | No | Set to true to reverse a previous approval back to pending |
Test Case Management
get_testcases
Fetch test cases with optional filtering. Returns simplified list by default (TestcaseID, Title, Description). By default returns only active test cases (excludes archived, in-creation, and issue-linked).
| Parameter | Type | Required | Description |
|---|---|---|---|
| detailed | boolean | No | Set to true for full details (steps, assertions). Only use with testCaseIds to avoid large responses |
| testCaseIds | string | No | Comma-separated list of test case IDs (e.g., 1,2,3) |
| archived | string | No | Filter: true for archived only, false for non-archived only |
| status | string | No | Comma-separated from active, in-creation, archived, issue-linked |
| testSuiteId | string | No | Filter by test suite ID |
| cursor | string | No | Pagination cursor |
create_custom_testcase
Create and automatically queue a new test case from a natural language prompt. The test will be generated, queued, and executed automatically.
| Parameter | Type | Required | Description |
|---|---|---|---|
| prompt | string | Yes | Natural language description of the test case to create |
| runId | string | No | Run ID to execute against. Defaults to the latest default run |
| credentialId | string | No | Credential ID to use. Use get_credentials to find available IDs |
| bundleId | string | No | Override URL for web app tests |
run_specific_testcases
Execute existing test cases by their IDs. If you have a description instead of IDs, call get_testcases first to find the matching IDs.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseIds | integer[] | Yes | Array of numeric test case IDs to execute (e.g., [123, 456]) |
| runId | string | No | Run ID to execute against. Defaults to the latest run |
update_testcase
Update an existing test case’s title, description, steps, assertions, and/or key feature assignment. Supports partial updates.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseId | integer | Yes | The ID of the test case to update |
| title | string | No | New title |
| description | string | No | New description |
| steps | string[] | No | New array of test steps |
| assertions | string[] | No | New array of assertions |
| groupId | string | No | Key feature ID to assign. Use manage_key_features with action=get to list available IDs |
| credentialId | string | No | Credential ID to assign |
| bundleId | string | No | Override URL for web app tests. Set empty string to clear |
archive_testcases
Archive test cases by marking them as archived.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseIds | integer[] | Yes | Array of test case IDs to archive |
unarchive_testcases
Unarchive previously archived test cases.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseIds | integer[] | Yes | Array of test case IDs to unarchive |
add_testcase_to_suite
Add a custom test case to the main test suite (default suite). Removes the test case from in-creation status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseId | integer | Yes | The ID of the test case to add to the main suite |
Test Results & Findings
get_results
Fetch test execution results with optional filtering. Returns simplified results by default (Test ID, Title, Pass/Fail, Reasoning, Findings).
| Parameter | Type | Required | Description |
|---|---|---|---|
| detailed | boolean | No | Set to true for step-by-step execution details. Only use with testCaseIds to avoid large responses |
| runID | string | No | Run ID to fetch results for. Defaults to the latest run |
| testCaseIds | string | No | Comma-separated test case IDs to filter |
| status | string | No | Filter by result: Pass or Fail |
| withImages | string | No | Set to true to include image URLs in execution steps |
| cursor | string | No | Pagination cursor |
get_findings
Fetch findings for a specific run. Findings are run-specific and emerge from test cases. Issues are de-duplicated findings at the app level.
| Parameter | Type | Required | Description |
|---|---|---|---|
| runID | string | No | Run ID. Defaults to the latest run |
| status | string | No | Filter: pending, approved, or rejected |
| testCaseId | string | No | Filter findings for a specific test case |
| cursor | string | No | Pagination cursor |
approve_findings
Confirm findings as valid. Changes triage state from pending to approved.
| Parameter | Type | Required | Description |
|---|---|---|---|
| findingIds | string[] | Yes | Array of finding IDs to approve |
| runID | string | No | Run ID where findings are located. Defaults to the latest run |
reject_findings
Mark findings as false positives.
| Parameter | Type | Required | Description |
|---|---|---|---|
| findingIds | string[] | Yes | Array of finding IDs to reject |
| rejectReason | string | No | Reason for rejecting |
| runID | string | No | Run ID. Defaults to the latest run |
Test Run Management
create_run
Create a new test run.
| Parameter | Type | Required | Description |
|---|---|---|---|
| buildID | string | No | Build ID to associate with the run |
| osVersion | string | No | OS version for test execution (e.g., 18.2 for iOS, 33 for Android) |
run_discovery
Create a new discovery run to automatically explore the app and generate test cases. Only works if the app has no existing test cases.
| Parameter | Type | Required | Description |
|---|---|---|---|
| buildID | string | No | Build ID to associate with the discovery run |
get_runs
Fetch all test runs for the application. Returns run IDs, build info, status, and timestamps.
| Parameter | Type | Required | Description |
|---|---|---|---|
| cursor | string | No | Pagination cursor |
Key Features
manage_key_features
Manage key features (also called “groups”) that organize test cases into logical groups.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | get to fetch all, add to create, update to modify, delete to remove |
| keyFeatures | object[] | No | Array of key feature objects (required for add, update, delete) |
Key feature object properties:
| Property | Type | Description |
|---|---|---|
| id | string | Unique identifier. Used as groupId on test cases. Required for update/delete |
| name | string | Display name. Required for add/update |
| description | string | Description of the feature |
| icon | string | Icon identifier. Use get_available_icons to see options |
| prompts | string[] | Associated prompts |
| sortIndex | integer | Sort order for display |
| star | boolean | Whether this feature is starred |
get_available_icons
Get the list of available radix-ui icons for key features. No parameters.
Test Suites
create_test_suite
Create a new test suite to organize test cases into logical groups.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Suite name (e.g., “Smoke Tests”, “Regression Suite”) |
| testCaseIds | integer[] | No | Test case IDs to include |
| suiteInstructions | string | No | Custom instructions that override app-level instructions |
| suiteURL | string | No | Custom URL for browser platforms only |
| osVersion | string | No | Android OS version (e.g., 30, 33) |
get_test_suites
List all test suites for the application. Returns suite names, IDs, and test case counts. No parameters.
update_test_suite
Update an existing test suite. Supports partial updates.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testSuiteId | string | Yes | ID of the test suite to update |
| name | string | No | New name |
| addTestCaseIds | integer[] | No | Test case IDs to add |
| removeTestCaseIds | integer[] | No | Test case IDs to remove |
| suiteInstructions | string | No | Updated custom instructions |
| suiteURL | string | No | Updated URL (browser platforms only) |
| osVersion | string | No | Updated Android OS version |
delete_test_suite
Delete a test suite. Test cases are NOT deleted, just unlinked from the suite.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testSuiteId | string | Yes | ID of the test suite to delete |
Credentials
get_credentials
Fetch all credentials for the current app. Returns credential ID, name, username, and default status. Passwords are not returned. No parameters.
create_credential
Create a new login credential for the app.
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | Yes | Login username |
| password | string | Yes | Login password |
| name | string | Yes | Friendly name (e.g., “Admin User”, “Test Account”) |
| isDefault | boolean | No | Set to true to make this the default credential |
Scripts
get_scripts
Fetch all execution scripts for the current app. Scripts are shell commands referenced in test steps using #{script-name} syntax. No parameters.
create_script
Create a new execution script.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Script name used for #{name} syntax in test steps |
| instructions | string | Yes | Shell command(s) to execute when invoked |
App Configuration & Admin
get_app
Fetch app configuration and details including ID, name, platform, and settings. No parameters.
get_apps
Admin only. List all apps available to switch to. No parameters.
search_apps
Admin only. Search for apps by name (case-insensitive partial match).
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search query to match against app names |
switch_app
Admin only. Switch the active app for this MCP session. All subsequent tool calls will operate on the specified app.
| Parameter | Type | Required | Description |
|---|---|---|---|
| app_id | string | No | App ID to switch to. Omit to reset to the default app |
Advanced Testing
trigger_rediscovery
Trigger rediscovery for an existing test case to detect product changes and auto-update the test.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseID | integer | Yes | The test case ID to trigger rediscovery for |
| rediscoveryInstructions | string | No | Context about what changed (e.g., “The navigation menu was redesigned”) |
get_step_doms
Fetch DOM (HTML) content for each step of a test case execution. DOMs can be large - use stepIds to limit scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseId | string | Yes | Test case ID to fetch DOMs for |
| runID | string | No | Run ID. Defaults to the latest run |
| stepIds | string | No | Comma-separated step IDs to filter (e.g., 1,3,5) |
| cursor | string | No | Pagination cursor |
generate_tests_on_local
Generate a terminal command template for running local test case exploration on localhost URLs.
| Parameter | Type | Required | Description |
|---|---|---|---|
| prompts | string[] | No | Array of test case descriptions/prompts |
| localhost_url | string | No | Local URL where the website is hosted |
start_test_monitoring
Fetch test results and findings for a completed test case. Only call this after the test execution has finished.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseId | string | Yes | Test case ID from completed test execution |
| runId | string | No | Run ID associated with the test execution |
Bounding Box Evaluation
get_bbox_evaluations
Fetch pending bounding box evaluations that need human correction.
| Parameter | Type | Required | Description |
|---|---|---|---|
| isProcessed | string | No | Filter: true or false |
| isVerified | string | No | Filter: true for verified, false for pending |
| limit | string | No | Max evaluations to return (1-100, default 50) |
submit_bbox_correction
Submit a corrected bounding box for a test case step.
| Parameter | Type | Required | Description |
|---|---|---|---|
| testCaseId | string | Yes | Test case ID |
| runId | string | Yes | Run ID |
| seqId | string | Yes | Sequence ID |
| stepId | string | Yes | Step ID |
| correctedBBox | string | Yes | Corrected bounding box as JSON array: [x, y, width, height] |
Utility
health_check
Check the health of the Pie API service. Verifies connectivity and authentication. No parameters.
Pagination
Tools that return lists support cursor-based pagination. When more results are available, the response includes a cursor value. Pass it as the cursor parameter in your next call to fetch the next page. Omit cursor for the first page.