Async Jobs

Async Jobs

Long-running MATLAB code is automatically handled through the async job system.

How It Works

1. You call execute_code with your MATLAB code
2. The server starts executing synchronously
3. If execution exceeds sync_timeout (default 30 seconds), the job is promoted to async
4. You get back a job_id immediately
5. Poll get_job_status for progress updates
6. Call get_job_result when the job completes

Job Lifecycle

PENDING → RUNNING → COMPLETED
                  → FAILED
                  → CANCELLED

State Transitions

• PENDING: Job created, waiting for execution to start
• RUNNING: Execution has begun on an engine
• COMPLETED: Execution finished successfully with a result
• FAILED: Execution encountered an error
• CANCELLED: Job was cancelled via cancel_job before completion

Sync Execution

Short-running code completes within the sync_timeout window (default 30 seconds):

% This returns immediately with status="completed"
result = 1 + 1;
disp(result);

The result is returned inline:

{
  "status": "completed",
  "job_id": "j-...",
  "text": "2"
}

Async Promotion

If execution takes longer than sync_timeout, the job is automatically promoted to async:

% If this takes > 30s, it becomes an async job
n = 1e7;
for i = 1:n
    x = sqrt(i);
end
disp('Done');

Response on promotion:

{
  "status": "pending",
  "job_id": "j-abc123def"
}

The job continues running in the background while you poll for status.

Job Status Polling

Call get_job_status to check the current state and progress:

{
  "job_id": "j-abc123def",
  "status": "running",
  "progress": 45,
  "message": "Processing batch 450/1000",
  "elapsed_seconds": 12.5
}

Poll periodically until status transitions to completed, failed, or cancelled.

Progress Reporting

Use the mcp_progress() helper function in your MATLAB code to report progress back to the agent:

mcp_progress(__mcp_job_id__, percentage, message)

• __mcp_job_id__ — automatically injected into the workspace by the server
• percentage — number from 0 to 100
• message — optional status message

How Progress Works Internally

1. mcp_progress.m writes a JSON file to __mcp_temp_dir__/<job_id>.progress
2. get_job_status reads this file and includes progress in the response
3. The file is cleaned up when the job completes

Example

n = 1e6;
results = zeros(n, 1);
for i = 1:n
    results(i) = process_item(i);
    if mod(i, 1e5) == 0
        mcp_progress(__mcp_job_id__, i/n*100, ...
            sprintf('Processed %d/%d items', i, n));
    end
end
disp(mean(results));

Agent polling sees:

get_job_status → {status: "running", progress: 10, message: "Processed 100000/1000000 items"}
get_job_status → {status: "running", progress: 50, message: "Processed 500000/1000000 items"}
get_job_status → {status: "running", progress: 100, message: "Processed 1000000/1000000 items"}
get_job_result → {status: "completed", text: "0.5023"}

Job Result Retrieval

Call get_job_result to retrieve the output of a completed job:

{
  "job_id": "j-abc123def",
  "status": "completed",
  "text": "Final result: 42",
  "variables": {
    "ans": 42,
    "result": [1, 2, 3]
  }
}

For failed jobs:

{
  "job_id": "j-abc123def",
  "status": "failed",
  "error": {
    "type": "MATLABExecutionError",
    "message": "Undefined variable 'x'",
    "matlab_id": null,
    "stack_trace": "..."
  }
}

Job Cancellation

Cancel a pending or running job with cancel_job:

{
  "job_id": "j-abc123def"
}

The job transitions to cancelled status. The MATLAB engine executing the job is returned to the pool.

Retention and Cleanup

Completed, failed, and cancelled jobs are retained for job_retention_seconds (default 86400 = 24 hours) before automatic pruning:

• Job metadata is kept for historical reference
• Old job records are periodically removed to free memory
• Active jobs (PENDING, RUNNING) are never pruned

To check a job that was pruned, call get_job_status or get_job_result — it will return job_not_found.

Job Management Tools

Tool	Description
execute_code	Create and start a job with MATLAB code
get_job_status	Current status, progress percentage, and elapsed time
get_job_result	Full result of a completed/failed job
cancel_job	Cancel a pending or running job
list_jobs	List all jobs in the session

Configuration

execution:
  sync_timeout: 30              # Seconds before async promotion
  max_execution_time: 86400     # Hard limit (24h)

sessions:
  job_retention_seconds: 86400  # Keep job metadata for 24h

Tips

• Short code (< 30s): Results return inline, no job ID needed
• Medium code (30s - minutes): Auto-promoted, poll with get_job_status
• Long code (hours): Add mcp_progress() calls so the agent can report status
• Cancel: Call cancel_job if you need to stop a running job
• Increase timeout: Set sync_timeout: 60 if most of your code takes 30-60s
• Progress updates: Call mcp_progress() frequently for responsive agent feedback
• Historical lookup: Retrieve completed job results within the retention window; older jobs are automatically cleaned up