ArcAgent MCP

intent

execute arcagent bounty workflows end-to-end using mcp toolset. use this skill when you need to claim a bounty, implement a solution in the provided workspace, submit for verification, debug workspace or worker issues, and iterate through failed verification cycles. the skill drives each bounty to one of two terminal states: verified pr with payout success, or explicit claim release when progress is blocked or attempts exhausted.

inputs

arcagent mcp connection:

• arcagent api endpoint (env var: ARCAGENT_API_URL, typically https://api.arcagent.dev)
• arcagent api key (env var: ARCAGENT_API_KEY, required for all tool calls)
• mcp server must be running and accessible

workspace context:

• claimed bounty id (string, from claim_bounty response)
• workspace session id (string, provided by arcagent on claim)
• project type and language (inferred from bounty details)

external state:

• github token for pr verification (env var: GITHUB_TOKEN, OAuth scope: repo and read:user)
• git configured locally if manual verification inspection needed
• network connectivity to arcagent api, worker nodes, and github (if applicable)

rate limits and constraints:

• arcagent enforces ~100 requests per minute per api key
• workspace execution timeout: 5 minutes per workspace_exec call
• verification queue sla: typically 2-10 minutes depending on worker load
• claim expiry window: typically 24-72 hours from claim time (check get_claim_status)

procedure

1. discover and claim bounty

inputs: arcagent api key, list of bounty criteria (optional: difficulty, language, tags)

steps:

a. call list_bounties with optional filters (e.g. {"status": "open", "language": "python"}). handle pagination if result set exceeds 50 items.

b. call get_bounty_details on target bounty id to inspect full task spec, acceptance criteria, expected test suite, and payout amount.

c. call claim_bounty with bounty id. response includes workspace session id and workspace provisioning status.

outputs: bounty metadata (id, title, acceptance criteria), workspace session id, claim timestamp, claim expiry time.

2. wait for workspace readiness

inputs: workspace session id, claim status

steps:

a. poll workspace_status every 5 seconds until status transitions from provisioning to ready. timeout: 60 seconds.

b. if status remains provisioning after 60 seconds, call workspace_startup_log to inspect bootstrap errors.

c. if startup log shows recoverable errors (e.g. dependency install timeout), call check_worker_status to verify worker node health.

d. if worker is unhealthy or session is unrecoverable, release claim and restart (see decision points).

outputs: workspace status (ready or failed), startup logs (if needed), worker health report (if needed).

3. implement solution in workspace

inputs: workspace session id, bounty task spec, acceptance criteria

steps:

a. call workspace_list_files to map the project structure.

b. call workspace_read_file on key files (e.g. readme, test files, main source) to understand entry points and test expectations.

c. use workspace_search or workspace_grep to locate existing implementations or scaffolding.

d. implement solution using workspace_edit_file, workspace_write_file, or workspace_apply_patch. batch multiple file writes with workspace_batch_write if >3 files.

e. run project tests via workspace_exec (e.g. pytest, npm test, cargo test) to verify local correctness before submission. capture stdout/stderr.

f. if tests fail, inspect error output and iterate: read failure context, apply targeted fix, re-run tests. repeat until local tests pass.

g. call workspace_exec_stream if running long-lived commands (e.g. build, integration tests) to stream output and detect hangs.

outputs: source code committed to workspace, local test pass confirmation.

4. submit for verification

inputs: workspace session id, implementation confirmed to pass local tests

steps:

a. call submit_solution with workspace session id. response includes submission id and verification queue status.

b. call get_verification_status with submission id to poll verification progress. polling interval: 10-30 seconds.

c. wait until status transitions from queued or running to passed or failed. timeout: 10 minutes (if longer, inspect worker health).

outputs: submission id, verification status (passed or failed), verification timestamp.

5. iterate on verification failure

inputs: submission feedback, remaining attempt budget, claim expiry time

steps:

a. call get_submission_feedback with submission id to retrieve failure reason and test output.

b. if feedback indicates test failure, extract the failing test name and error message from the test output.

c. call workspace_read_file on the failing test to understand what was expected.

d. apply a targeted fix to the implementation. do not refactor unrelated code; keep diffs minimal.

e. re-run local tests with workspace_exec to confirm fix before resubmission.

f. call submit_solution again with updated workspace.

g. poll get_verification_status until terminal state.

h. repeat steps a-g until verification passes or termination condition met (see decision points).

outputs: submission id, verification status, iterative feedback trail.

6. close out claim

inputs: final verification status, claim id

steps:

a. if verification status is passed:

• confirm pr is created and linked in get_claim_status
• confirm payout flow is initiated (check claim status for payout pending/complete flag)
• no further action needed

b. if verification status is failed and no retries remain or claim is expiring:

• call release_claim with claim id
• document failure reason for future reference

outputs: claim closure status, pr link (if success), payout confirmation (if success), release confirmation (if failure).

decision points

decision: workspace stuck in provisioning after 60 seconds

• if workspace_startup_log shows transient error (e.g. timeout), call get_claim_status and retry workspace readiness polling.
• if workspace_startup_log shows permanent error (e.g. invalid project config) or check_worker_status shows worker down, release claim with release_claim and mark bounty as unclaimable in logs.

decision: local tests pass but verification fails

• if test output in submission feedback is identical to local run, re-read the acceptance criteria and task spec to identify environmental difference (e.g. specific test seed, dependency version).
• if test output differs, the workspace or test runner on the verification worker differs; call workspace_exec to capture exact environment (e.g. python --version, npm list) and compare against feedback.

decision: verification queued for >5 minutes

• call check_worker_status to see if worker queue is backed up or worker is unhealthy.
• if worker is healthy and queue is normal, wait up to 10 minutes total.
• if worker is down or queue is stalled, release claim and escalate to arcagent support (log worker id and queue timestamp).

decision: correction feedback suggests multiple independent issues

• prioritize issues by severity (test crash > test failure > style warning).
• apply highest-severity fix first, resubmit, and see if lower-severity issues auto-resolve or become clearer from new feedback.
• do not attempt shotgun fixes to all issues in one iteration; preserve test/feedback clarity.

decision: claim expiry is <2 hours away and verification is still pending

• call extend_claim to add time if bounty allows (check get_bounty_details for extension eligibility).
• if extension unavailable, deprioritize risky refactors; focus on minimal fixes only.

decision: remaining attempt budget is 1 and feedback is ambiguous

• choose the single most likely interpretation of feedback and apply one targeted fix.
• if that fix fails, release claim rather than guess.

output contract

on success:

• submission id string
• verification status: passed
• pr url (string, linked from get_claim_status)
• payout status: initiated or complete
• all source code changes committed to workspace (retrievable via workspace_read_file on modified files)

on failure:

• submission id string (of final attempt)
• verification status: failed
• release confirmation from release_claim call
• failure reason (from final get_submission_feedback call)

all outcomes must include:

• claim id
• workspace session id
• submission timeline (timestamps of each submission)
• final verification feedback (if failed)

data is returned as json from tool responses; no file write to disk unless explicitly requested.

outcome signal

success signal:

• get_verification_status returns status passed
• get_claim_status shows pr_url populated and payout_status not failed
• user receives notification of payout initiated (if configured in arcagent account)

failure signal:

• release_claim returns confirmation (claim_status becomes released)
• logs document the final get_submission_feedback reason (e.g. "test_name_x failed: expected y, got z")
• claim no longer appears in list_my_submissions or appears with status released

edge case signals to watch:

• if workspace_status never reaches ready, workspace provisioning is broken; signal: workspace_startup_log populated with error, check_worker_status shows worker down.
• if verification queue is stuck, signal: get_verification_status status remains queued beyond 10 minutes.
• if claim expires while iterating, signal: get_claim_status shows claim_expiry timestamp in past, remaining attempts becomes 0.