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

Execution Flow

1. Job Creation: A new job is created in PENDING state when execute_code is called
2. Engine Acquisition: An available MATLAB engine is acquired from the pool
3. Context Injection: Job context is injected into the MATLAB workspace (__mcp_job_id__, __mcp_temp_dir__, and mcp_progress function)
4. Background Execution: Code execution starts in the background with stdout/stderr capture
5. Sync Wait: The server waits up to sync_timeout seconds for completion
   • If completed: Result is returned inline with status: "completed"
   • If timeout: Job is promoted to async with status: "pending", and a background task monitors completion
6. Result Retrieval: Call get_job_result to fetch the completed result, or check get_job_status for progress
7. Cleanup: Job metadata is retained for job_retention_seconds (default 24h) before being pruned

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

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));

The agent sees:

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

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

Job Management Tools

Tool	Description
get_job_status	Current status + progress percentage + elapsed time
get_job_result	Full result of a completed job; error details if failed
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 before pruning

Error Handling

When a job fails, get_job_result returns error details including:

• error_type — exception class name
• message — error message
• matlab_id — MATLAB-specific error ID (if applicable)
• stack_trace — MATLAB stack trace (if applicable)

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
• Output capture: stdout and stderr are automatically captured for all jobs and included in results