MCP Execution Tools

Tools for monitoring and managing skill executions over MCP.

Skills are not executed over MCP. A tracked execution is started through the REST API (POST /api/v1/skills/:slug/run or POST /api/v1/executions). An agent asked to use a skill in chat carries it out in its own sandbox and creates no execution. Over MCP, these tools let you check status, list past runs, read a finished run’s diffs, and cancel an active execution. To follow a run in real time, mint a signed stream URL and open it:
GET /api/v1/executions/:executionId/stream-token
See Executions for event types.

get-execution-status

Check the status of the current or most recent skill execution.

Parameters

None required.

Example

{
  "tool": "get-execution-status",
  "arguments": {}
}

Response (Running)

{
  "success": true,
  "data": {
    "executionId": "exec_abc123def456",
    "status": "running",
    "skillSlug": "readme-generator",
    "startedAt": "2024-01-15T10:30:00.000Z"
  }
}

Response (Idle)

{
  "success": true,
  "data": {
    "status": "idle",
    "message": "No active executions"
  }
}

list-executions

List recent skill executions with their status and results.

Parameters

Parameter	Type	Required	Default	Description
`limit`	number	No	20	Max results (1-100)
`offset`	number	No	0	Offset for pagination

Example

{
  "tool": "list-executions",
  "arguments": {
    "limit": 10
  }
}

Response

{
  "success": true,
  "data": [
    {
      "executionId": "exec_abc123",
      "skillSlug": "readme-generator",
      "skillName": "README Generator",
      "status": "completed",
      "cost": 45,
      "artifactId": "art_abc123",
      "startedAt": "2024-01-15T10:30:00.000Z",
      "completedAt": "2024-01-15T10:31:30.000Z",
      "hasConnectorResult": false,
      "connector": { "type": "remote", "fields": {} }
    },
    {
      "executionId": "exec_def456",
      "skillSlug": "code-reviewer",
      "skillName": "Code Reviewer",
      "status": "completed",
      "cost": 120,
      "artifactId": "art_def456",
      "startedAt": "2024-01-15T09:15:00.000Z",
      "completedAt": "2024-01-15T09:18:45.000Z",
      "hasConnectorResult": false,
      "connector": { "type": "remote", "fields": {} }
    }
  ],
  "pagination": { "hasMore": true }
}

cancel-execution

Cancel an active skill execution.

Parameters

Parameter	Type	Required	Description
`executionId`	string	No	Execution ID to cancel (defaults to current execution)

Example

{
  "tool": "cancel-execution",
  "arguments": {}
}

Response

{
  "success": true,
  "data": {
    "cancelled": true,
    "executionId": "exec_abc123"
  }
}

Errors

Code	Description
`NOT_FOUND`	No active execution or execution already completed

get-execution-diff

Get the full file diffs (content and unified diff) for a completed execution. Only the execution’s owner can read them.

Parameter	Type	Required	Description
`executionId`	string	Yes	ID of the execution whose diffs to fetch

Monitoring Workflow

Typical Flow

1. A skill execution is started through the REST API.

2. MCP client:
   - Calls get-execution-status() to see if a run is active
   - Calls list-executions() to review recent runs and their results
   - Calls list-artifacts() / get-artifact(id) to retrieve generated output

3. To follow a run live, mint a signed stream URL and open it:
   GET /api/v1/executions/:executionId/stream-token

Handling Long Executions

Executions can take up to 60 minutes. The MCP client should:

Poll get-execution-status or list-executions periodically
Or open the signed SSE stream URL for the execution
Or instruct the user to check the mobile app