MCP server

The MCP server exposes AgentServe to agents as five tools. It runs over stdio, is a thin client of the HTTP API, and shares the CLI's state file: a stack deployed through MCP can be managed with the CLI, and the other way round. Every tool takes the project directory as path; the stack linked to it is found in path/.agentserve/stack.json.

Running it#

The server ships in the agentserve package with the mcp extra. Your agent launches it on your machine, over stdio; uvx fetches it on first use:

uvx --from 'agentserve[mcp]' agentserve-mcp

Without the extra installed, it exits with the MCP server needs the 'mcp' extra: uvx --from 'agentserve[mcp]' agentserve-mcp. A client configuration that launches it:

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

See Connect your agent for client-specific setup.

Environment variables#

Variable	Default	Meaning
AGENTSERVE_URL	https://agentserve.sh	Server base URL.
AGENTSERVE_API_KEY	none	An account API key. New stacks are created in that account, with no TTL and no claim URL.

Return values and errors#

Tools return the JSON body of the API response. When the API answers with a status of 400 or above, the tool returns {"error": <detail>, "status_code": <status>} instead of raising. The exceptions are get_logs, which returns the response text as is, and any tool other than deploy_stack called on a directory with no linked stack, which raises no stack linked to <path>; call deploy_stack first.

deploy_stack#

Deploys or redeploys the directory at path. Reads agentserve.yaml if present, otherwise infers a single service. Waits for the build to finish before returning.

Argument	Type	Default	Meaning
path	string	required	Project directory.
ttl	string	server default, 1h	Lifetime of a new unclaimed stack, e.g. 30m. New stacks only.
name	string	directory name if there is no manifest	Stack name. New stacks only.
new	boolean	false	Ignore the linked stack and create a new one.

New stack: returns the stack object plus claim_code, claim_url, note and, when the manifest sets notify.webhook, webhook_secret. The manage_token is written to the state file and removed from the result, so it doesn't end up in the transcript.

Redeploy: returns the stack object plus the claim_url from the state file. Check deploy_error: if it is set, the new version failed and the previous one is still serving. If the redeploy is refused (expired, revoked token without AGENTSERVE_API_KEY, or a build already running), the tool returns error and status_code with a hint, and the directory stays linked; pass new=True to start a separate stack. Only when the linked stack was deleted is a new one created, and the result then carries a note saying the URLs changed.

Unlike the CLI, this tool has no claim_email argument; set claim_email in the manifest instead.

{
  "id": "stk_3f9a1c0b2d4e",
  "name": "todo-app",
  "status": "live",
  "claimed": false,
  "urls": {
    "api": "https://api-todo-app-3f9a.agentserve.sh",
    "web": "https://web-todo-app-3f9a.agentserve.sh"
  },
  "expires_at": 1791648131.2,
  "deploy_error": null,
  "claim_code": "CLM-7KQ2-M9XD-4HTW",
  "claim_url": "https://agentserve.sh/claim/CLM-7KQ2-M9XD-4HTW",
  "note": "Unclaimed stacks expire. Give claim_url to your human so they can keep this stack."
}

The example is abridged; the full field list is in HTTP API.

stack_status#

Status, URLs and expiry of the stack linked to path.

Argument	Type	Meaning
path	string	Project directory.

Returns the stack object from GET /v0/stacks/{id}, including role.

get_logs#

Runtime or build logs of the linked stack. Use it after a failed deploy.

Argument	Type	Default	Meaning
path	string	required	Project directory.
service	string	all services	Only this service.
build	boolean	false	Build logs instead of runtime logs.
tail	integer	200	Last lines per service.

Returns plain text, one section per service headed ### <service> (run|build). On an error, the text is the API's JSON error body.

extend_ttl#

Sets the expiry of an unclaimed stack to now plus ttl.

Argument	Type	Meaning
path	string	Project directory.
ttl	string	Duration, e.g. 1h.

Returns the updated stack object. Errors: 409 for a claimed or expired stack, 422 for an invalid duration or an expiry past the limit for unclaimed stacks.

destroy_stack#

Deletes the linked stack and its data, then removes the state file.

Argument	Type	Meaning
path	string	Project directory.

Returns {"id": "stk_…", "status": "deleted"}.

Not available over MCP#

Events and claiming have no tool. Use agentserve events and agentserve claim, or GET /v0/stacks/{id}/events and POST /v0/claim.