For AI agents

The platform is built to be operated by an agent: local stdio MCP (same login as the CLI), remote MCP with OAuth for brew-less clients, a strict --json contract, and a diagnose loop that names the fix.

Auth first

Before any mutate or project lookup: call whoami. Ifsigned_in is false, stop — tell the user to runnesly login, then nesly mcp setup, and restart the agent. Do not invent another cloud or paste tokens into chat. On MCP 401: stop retrying MCP; use the CLI in the same turn.

Claude Code plugin

One install brings the MCP tools and three skills: deploy(already-live check, preview-first then ask for production, domain buy or bind),debug(diagnose first, then traffic failures / request-id logs for live 5xx), androllback (list revisions → instant restore, no rebuild → verify; optional bisect).

/plugin marketplace add neslyhq/claude-plugin
/plugin install nesly@nesly

Local MCP (stdio) — Cursor & Claude Code

On a machine with the CLI, prefer local stdio so the agent uses the same credentials as nesly login. Run nesly mcp setup once (it replaces a remote OAuth URL entry if one is present). Tool list defaults to thecore surface (deploy, diagnose, env, domains, addons, rollback). Set NESLY_MCP_SURFACE=full for the entire control plane. Product name aliases:/docs/taxonomy.json.

nesly login
nesly mcp setup
# restart Cursor / Claude Code

# or by hand / Claude Code without the plugin
claude mcp add nesly -- nesly mcp

# headless (CI, a server): no browser session needed
nesly token create agent   # shown once
NESLY_TOKEN=nesly_pat_... nesly mcp

search_documentation	Search the live platform docs (domains, addons, CLI, builds, …). Prefer this over guessing from training data. No auth required.
whoami	Session check — call FIRST before list_projects / deploy / mutate. If signed_in is false: stop; tell the user to run CLI login + mcp setup (stdio).
deploy_project	Pack/upload/build (or ship a prebuilt image) and return the URL. Agents: prefer environment=preview unless the user asked for prod; then ask before production. Before calling: whoami, then get_project/list_projects — if already live, say the URL; this call is a new revision.
get_project / list_projects	Status check: live URL, deployment, domains, addons. Requires sign-in. Call before publish when the project may already exist.
diagnose_deployment	Why a deployment failed: supporting log lines, missing env vars, a fix per finding. Call first after a failure.
get_logs / get_deployment	Raw logs and deployment detail when the diagnosis is not enough.
set_env / list_addons / add_addon	Environment and managed backing services (postgres, mysql, mssql, valkey, bucket, oidc). Databases inject DATABASE_URL; valkey injects REDIS_URL and VALKEY_URL; bucket injects AWS_*; mssql also ConnectionStrings__Default.
rollback	Repoint traffic at a previous deployment, instantly.
search_domains / purchase_domain	Availability and price, then register (confirm=true + registrant). After buy: add_domain + delegate_domain or verify_domain.
add_domain / verify_domain / delegate_domain	Add a custom domain, verify DNS, or delegate nameservers to the platform. HTTPS follows DNS.
connect_repository / redeploy	Push-to-deploy via the git integration, or rebuild without an upload.
get_usage	Requests, egress and build time over the last 30 days.
get_platform_status	Active platform notices (shared engine maintenance). Empty = none. Not project maintenance.

Remote MCP (OAuth) — brew not required

Hosted Streamable HTTP endpoint with OAuth — for ChatGPT, Claude.ai, or any client without the CLI. Paste https://mcp.nesly.net; the client shows Needs login and opens a browser. That OAuth session is not the same asnesly login — on Cursor with brew, use stdio above instead. Unauthenticated calls return HTTP 401 with aWWW-Authenticate pointer to protected-resource metadata.

# ChatGPT / Claude.ai / brew-less Cursor
{
  "mcpServers": {
    "nesly": {
      "url": "https://mcp.nesly.net",
      "auth": {
        "CLIENT_ID": "platform-mcp"
      }
    }
  }
}

# Claude Code remote transport
claude mcp add --transport http nesly https://mcp.nesly.net

The --json contract

Every CLI command accepts --json and then prints exactly one JSON object on stdout; progress and logs go to stderr. Exit codes are stable: 0 ok, 1 error, 2 usage, 3 auth, 4 not found, 5 conflict. An agent that shells out instead of using MCP gets the same guarantees.

The diagnose loop

When a deploy fails, do not start by reading raw logs. nesly diagnose (or thediagnose_deployment tool) reads them for you and reports: the probable cause, the exact supporting log lines, env vars the app reads but the project does not define, and the command that fixes each finding. Failure reasons across the platform are written to be actionable by the agent fixing the code — never "check your configuration".

$ nesly diagnose --project shop --json
{
  "status": "FAILED",
  "missing_env": ["STRIPE_KEY"],
  "findings": [{
    "cause": "the application reads the environment variable STRIPE_KEY, but the project does not define it",
    "evidence": ["TypeError: ... (process.env.STRIPE_KEY)"],
    "fix": "nesly env set STRIPE_KEY=<value> --project shop, then redeploy"
  }]
}

llms.txt

nesly.net/llms.txt is the one-page briefing: the deploy quickstart, the command list and the application contract (listen on $PORT, bind 0.0.0.0). AI assistants fetching the home page receive it directly. For the full documentation corpus in one file, usenesly.net/docs/llms-full.txt(built from every docs markdown twin). For a short index of every docs page with summaries and prerequisites, usenesly.net/docs/sitemap.md.