Skip to main content

​
Overview

The execute tool runs TypeScript code in a sandboxed execution environment with access to workspace tools via the tools object. Code is executed with configurable timeouts, and results are returned synchronously by default.

​
Endpoint

POST https://your-deployment.convex.site/mcp

​
Authentication

​
MCP Tool Call

MCP Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute",
    "arguments": {
      "code": "return tools.catalog.namespaces({})",
      "timeoutMs": 30000,
      "runtimeId": "cloudflare-worker",
      "waitForResult": true
    }
  }
}

​
Parameters

​
code
string
required
TypeScript code to execute. Use return to return a value. The code has access to a typed tools object for calling external services. Console output is not returned.
​
timeoutMs
number
default:"300000"
Maximum execution time in milliseconds (1-600000). Default is 5 minutes.
​
runtimeId
string
Runtime environment identifier. Defaults to workspace default runtime. Common values:
  • cloudflare-worker - Cloudflare Worker sandbox
  • local-bun - Local Bun runtime (self-hosted only)
​
metadata
object
Optional metadata to attach to the task for tracking and filtering.
​
sessionId
string
Session identifier for grouping related tasks. Used for anonymous context initialization.
​
waitForResult
boolean
default:"true"
Whether to wait for task completion before returning. When false, returns immediately with task ID.
​
resultTimeoutMs
number
Maximum time to wait for results in milliseconds (100-900000). Defaults to timeoutMs + 30000 with a minimum of 120 seconds.

​
Response

​
content
array
required
Array of text content objects with the execution summary.
​
structuredContent
object
Structured execution details.
​
isError
boolean
Indicates if the execution failed (status is not completed)

​
Examples

// MCP tool call
{
  "name": "execute",
  "arguments": {
    "code": "return 1 + 1"
  }
}

// Response
{
  "content": [
    {
      "type": "text",
      "text": "taskId: task_123\nstatus: completed\nruntimeId: cloudflare-worker\nexitCode: 0\n\n```json\n2\n```"
    }
  ],
  "structuredContent": {
    "taskId": "task_123",
    "status": "completed",
    "runtimeId": "cloudflare-worker",
    "exitCode": 0,
    "result": 2,
    "workspaceId": "workspace_abc",
    "accountId": "account_xyz",
    "sessionId": "session_123"
  }
}

​
Runtime Environment

The execution sandbox provides:
  • TypeScript support - Full TypeScript syntax and type checking
  • tools object - Typed methods for calling workspace-configured external services
  • No filesystem access - Use tools.* for all external interactions
  • No process/import access - Pure TypeScript execution only
  • Approval gates - Tool calls may require approval based on workspace policies

​
Tool Discovery Pattern

// Best practice: single broad discovery pass
const discovered = await tools.discover({ 
  query: 'github repos',
  limit: 12,
  compact: true // Get hints, not full schemas
});

// Use bestPath when available
if (discovered.bestPath) {
  const result = await tools[discovered.bestPath](params);
}

// Or iterate results
for (const tool of discovered.results) {
  console.log(tool.path, tool.hint);
}

​
Error Handling

  • Timeout errors - Task status becomes timed_out if execution exceeds timeoutMs
  • Runtime errors - Exceptions are captured in the error field with status failed
  • Approval denials - Tool calls denied by policy result in status denied
  • Exit codes - Non-zero exit codes indicate execution failures

​
Rate Limits

Rate limits are enforced per workspace:
  • Default: 100 requests per minute
  • Configurable via workspace settings
  • Returns 429 status when exceeded

Build docs developers (and LLMs) love

Get started for freeTalk to us