Connect your agent

An agent can drive AgentServe in four ways. They all talk to the same JSON API, and the CLI and the MCP server share the same state file, so a stack deployed with one can be managed with the other.

way	best when
CLI (agentserve)	The agent has a shell. Fewest moving parts.
MCP server (agentserve-mcp)	The agent supports MCP and you want typed tools rather than shell commands.
Skill file (/skill.md)	The agent should learn the workflow: when to deploy, what to tell the user, how to debug.
HTTP API (/v0)	Nothing can be installed, but the agent can make HTTP requests.

A skill file pairs well with either the CLI or the MCP server: the skill explains the workflow, the tool does the work. For step-by-step setup in a specific agent, see the build guides: Claude Code, Cursor, Codex, Windsurf, any MCP client and plain HTTP.

Environment variables#

The CLI and the MCP server read one optional variable:

variable	default	purpose
AGENTSERVE_API_KEY	unset	An account API key (as_live_…). Optional.

Without an API key, deploys are anonymous: they run on a 1h TTL and return a claim URL for the agent to pass on. With one, new stacks go straight into that account, with no claim code and no TTL, and agentserve claim works.

CLI#

Install it on your PATH with uv. Then:

uv tool install agentserve
agentserve deploy ./my-project           # deploy or redeploy, prints URLs and the claim URL
agentserve status ./my-project
agentserve logs ./my-project --build     # or --service api for runtime logs
agentserve extend ./my-project --ttl 30m
agentserve destroy ./my-project

The stack id and manage token are saved in ./my-project/.agentserve/stack.json (git-ignored), so repeated deploys update the same stack. deploy exits 1 when the build fails or a redeploy is rolled back, which agents can check directly. Every command and flag is in the CLI reference.

MCP server#

The MCP server runs over stdio on your machine, because it reads and packs your project directory. Register it in your agent's MCP configuration; uvx fetches it on first use:

{
  "mcpServers": {
    "agentserve": {
      "command": "uvx",
      "args": ["--from", "agentserve[mcp]", "agentserve-mcp"]
    }
  }
}

It exposes five tools, each taking the project directory as path:

• deploy_stack(path, ttl?, name?, new?): deploy or redeploy. Returns URLs, status and the claim_url. The manage token is written to the state file and left out of the result.
• stack_status(path): status, URLs and expiry.
• get_logs(path, service?, build?, tail?): runtime logs, or build logs with build=true.
• extend_ttl(path, ttl): move the expiry of an unclaimed stack.
• destroy_stack(path): delete the stack and its data.

The MCP server has no claim or events tool, and deploy_stack doesn't take a claim email; use the CLI or the API for those. Details in the MCP reference.

Skill file#

AgentServe serves a skill at /skill.md. It tells an agent how to deploy, what to hand the user afterwards (the URLs, the claim URL and the expiry time), how to read logs after a failure, and when not to claim on the user's behalf. It also summarises the HTTP API for agents without the CLI.

curl https://agentserve.sh/skill.md

The file has name and description front matter, so agents that load skills from files can use it as is. Others can be told to read it at the start of a task.

HTTP API#

If nothing can be installed, the agent can call the API directly. Pack the project as a tar.gz and post it:

tar -czf /tmp/src.tar.gz --exclude node_modules --exclude .git -C ./my-project .
curl -s -X POST "https://agentserve.sh/v0/stacks?wait=true" -F source=@/tmp/src.tar.gz

The response includes id, the service URLs, manage_token, claim_code and claim_url. Keep the manage token: later calls send it as Authorization: Bearer <manage_token> to GET, PATCH or DELETE /v0/stacks/{id}, to redeploy at POST /v0/stacks/{id}/deploy, and to read /logs and /events. To deploy into an account, send the API key as the bearer token on the create call instead. The full list of endpoints is in the API reference.

What the agent should tell the user#

Whatever the interface, an anonymous deploy is only useful if the human hears about it. After each deploy the agent should give the user the service URLs, the claim URL and the time the stack expires, for example: "Live at … until 15:40. Open the claim link to keep it." Five minutes before expiry the stack emits stack.expiring, a good moment for a reminder.