setup

Ample remote MCP

Endpoint: https://api.ample.computer/mcp (Streamable HTTP).
Local clients can continue using ample mcp over stdio.

The catalog comes from Clap's public command tree in the same release as the worker CLI. ample server list becomes ample_server_list. Adding an ordinary command or flag requires no MCP schema, routing, or argument mapping. The catalog is available through tools/list, /mcp/catalog, or ample docs mcp. /mcp/server.json and ample docs mcp --registry publish generated registry metadata, including the catalog digest. Process management (mcp, update) and local credential replacement (auth login, auth redeem) are excluded. The original seven MCP names and service_or_path/answers spellings remain.

Register and authenticate

An agent host must be able to provision and retain credentials. Browser-OAuth-only clients are outside this version. No CAPTCHA, payment, or browser interaction is required for a normal first deployment.

Send POST /v1/auth/signup with JSON:

{"name":"my-agent","request_key":"<fresh-random-UUID-v4>"}

Save the random request key before sending. Reuse it after a disconnect to retrieve the same encrypted registration receipt for ten minutes. Never share it. The response includes account identity, free quotas and budget, a claim URL, fixed account expiry, access_token, and credentials.client_id / client_secret. The ample_auth_signup MCP tool provides the same flow; its execution_key must be a UUID v4 when no explicit request_key is supplied. ample auth signup prints credentials without replacing an existing local CLI login.

Renew access by sending a form-encoded POST /oauth/token:

grant_type=client_credentials
client_id=<issued client ID>
client_secret=<issued secret>
resource=https://api.ample.computer/mcp

HTTP Basic client authentication is also supported. Access tokens last at most 15 minutes and are audience-bound. Send Authorization: Bearer <access_token> on every protected MCP/REST request. Existing scoped bearer tokens also work. Operator/admin tokens are rejected by remote MCP and never enter worker VMs. Authorization metadata is at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. The optional extension identifier is io.modelcontextprotocol/oauth-client-credentials.

Renewal never extends the account's original unclaimed lifetime (48 hours by default) or clears suspension. Use the returned claim URL to claim the account. ample_auth_agent_create/list/revoke manages agent credentials. Revocation fences access tokens and descendant credentials, including already admitted workers.

Supply code, plan, and deploy

  1. Call ample_workspace_create with a name and fresh execution_key.
  2. Populate the returned workspace ID through ample_workspace_write
    (id, path, text or data_base64), ample_workspace_upload
    (id, data_base64 containing a tar.gz), or ample_workspace_import
    (id, public HTTPS url, optional reference). For larger uploads, PUT the
    tar.gz directly to /v1/workspaces/<id>/archive with bearer authentication.
  3. Call ample_plan with workspace_id, path: ".", write: true, and a fresh
    execution_key. Resolve needs_input questions with answers, or edit
    ample.toml through the workspace file tools.
  4. Call ample_deploy with the same workspace_id and a fresh execution key.
    Read its result: deployment is synchronous. An unchanged redeploy is a no-op.
  5. Use ample_logs, server/database/app tools, and workspace download as needed.
    Delete the workspace when finished; deployed apps are independent resources.

Workspace tools use their explicit id argument; omit the common workspace_id context for these tools. Other calls use workspace_id as their current directory. Local path arguments must be relative and remain inside it. ample.toml and .ample deployment state survive between calls. A manifest can also provision a managed database through the normal CLI planner/deployer path. Private Git repositories can be supplied through uploads.

Workspaces allow 32 MiB compressed archives, 128 MiB expanded source, 16 MiB per file, and 10,000 files, within the account's unchanged storage allowance. Archives must contain regular files/directories; traversal, links, and special files are rejected. Git uses public HTTPS/443 only, pinned public IPv4 DNS answers, no credentials, no redirects, hooks, or submodule fetching. The resolved commit is recorded. Inactive workspaces expire after seven days; account expiry/deletion cleans them sooner. An unresolved suspension retains evidence for operator review.

Results, retries, and cancellation

Each tool result has structuredContent containing exit_code, result, and stderr. Exit 2 with result.status == "needs_input" is a normal planning response. CLI parsing errors are explicitly invalid_arguments and isError.

Every remote tool call requires an execution_key, unique for the intended action. Reuse the same key and arguments after a disconnect. It returns the existing execution; a key reused with different arguments is rejected. Use a new key after source/config edits. There are at most four active executions per account, one mutating execution per workspace, a one-hour execution deadline, and bounded output (4 MiB per stream and 3 MiB of serialized result). Completed results are retained for seven days within a 128 MiB per-account result budget; expired result keys remain tombstones and never repeat mutations. Workspace save failures preserve the command result and retain paused source for 24-hour operator recovery. Results include an execution_id; REST
GET /v1/executions/<id> also retrieves them.

Clients advertising io.modelcontextprotocol/tasks receive a task immediately and retrieve its result through tasks/get. Other clients wait synchronously; legacy progress notifications are sent when requested. Transport disconnects do not cancel durable work. Use tasks/cancel, ample_execution_cancel, or POST /v1/executions/<id>/cancel explicitly. Cancellation stops the worker; cloud mutations already accepted by the API may have completed. Inspect their operation/deployment result before retrying.

Abuse controls

The API and node runtime enforce account ownership, quotas, suspension, and fleet limits regardless of CLI/MCP/REST transport. Builders and workers retain the initiating account even when their VM records use an infrastructure account. Confirmed signature matches can block activation and suspend execution. Host CPU and outbound metrics trigger inspection; high CPU alone never suspends an account. Operators first validate detections in observation mode before enabling automatic suspension. No signature list can identify every abusive workload; VM CPU limits, the shared free CPU allowance, admission headroom, and network controls bound damage independently of detection.

Protocol references: Rust SDK,
Tasks,
client credentials.