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

Sync Execution

When you submit code:

1. A job is created in PENDING state
2. An engine is acquired from the pool
3. Job context is injected into the MATLAB workspace (including __mcp_job_id__ and __mcp_temp_dir__)
4. Code executes in the background with background=True
5. The server waits up to sync_timeout seconds for completion

Result: If the future completes within the timeout, the result is returned inline with status: "completed" (no polling needed).

Async Promotion

When execution exceeds sync_timeout:

1. The job transitions to background execution
2. The server returns immediately with status: "pending" and the job_id
3. A background task continues monitoring the job
4. You must poll get_job_status to track progress and completion

Result: Asynchronous background task handles job lifecycle; client polls for updates.

Job Status Polling

Use get_job_status to check progress:

→ get_job_status(job_id)
← {
    status: "running",
    progress: 25,
    message: "Processed 250000/1000000 items",
    elapsed_seconds: 12.5
  }

Repeat polling until status is one of: "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

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 → {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"}

How Progress Works Internally

1. mcp_progress() 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 Result Retrieval

Use get_job_result to retrieve the full result of a completed job:

→ get_job_result(job_id)
← {
    status: "completed",
    text: "0.5023",
    variables: {...}
  }

For failed jobs:

← {
    status: "failed",
    error: {
        type: "MATLAB:UndefinedFunction",
        message: "Undefined function or method 'process_item'",
        matlab_id: "MATLAB:UndefinedFunction",
        stack_trace: "Error in code (line 4)..."
    }
  }

Note: Results are retained in memory for job_retention_seconds (default 24 hours) after job completion.

Job Cancellation

Use cancel_job to stop a pending or running job:

→ cancel_job(job_id)
← {status: "cancelled", job_id: "j-..."}

Once cancelled, the job transitions to CANCELLED state and the background task is cleaned up. Results cannot be retrieved from a cancelled job.

Retention and Cleanup

Job metadata is retained according to job_retention_seconds (default 86400 = 24 hours):

• Active jobs (PENDING, RUNNING): Always retained while active
• Terminal jobs (COMPLETED, FAILED, CANCELLED): Retained for 24 hours after completion
• Automatic pruning: Expired jobs are removed by periodic cleanup; call list_jobs to see currently tracked jobs

To manually check which jobs exist:

→ list_jobs(session_id)
← [job_1, job_2, ...]

Job Management Tools

Tool	Description
execute_code	Submit MATLAB code for sync/async execution
get_job_status	Current status, progress percentage, and message
get_job_result	Full result of a completed job
cancel_job	Cancel a pending or running job
list_jobs	List all tracked jobs in a 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
• Elapsed time: get_job_status includes elapsed_seconds to monitor long-running jobs