# 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: ```json {"name":"my-agent","request_key":""} ``` 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`: ```text grant_type=client_credentials client_id= client_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 ` 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//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/` 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//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](https://docs.rs/rmcp/3.4.0/rmcp/), [Tasks](https://modelcontextprotocol.io/extensions/tasks/overview), [client credentials](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials).