Stagely

Connect a coding agent over MCP

View as Markdown

Connect Claude Code or another coding agent to Stagely over MCP, so it can deploy the pull request it opened, open the running app and test its change.

Stagely serves an MCP endpoint at /mcp on the Stagely console’s address. A coding agent connects with OAuth and acts as you. It acts in the one account that you choose on the consent page, with your role in that account. The agent deploys and tests its pull request. Then a person reviews the same stagelet.

Connect Claude Code

Add the server, then sign in.

claude mcp add --transport http \
  stagely https://app.stagely.dev/mcp
claude mcp login stagely

Your browser opens the consent page. If the page asks, sign in with GitHub. Choose the account and click Allow. You can also sign in from inside Claude Code: run /mcp, select stagely and authenticate.

Other MCP clients connect the same way: Stagely’s endpoint uses Streamable HTTP and OAuth with PKCE.

Tools

Tool Does
list_projects Lists the account’s projects. Each binds a GitHub repository to an environment.
list_stagelets Lists the account’s stagelets that are not deleted.
deploy_pull_request Builds and starts the head commit of an open pull request as a stagelet. Returns at once with the state deploying.
get_stagelet Gets a stagelet: its lifecycle state and last error, its machine and app health, whether the gateway reaches it, and both the revision that runs and the newest revision requested.
get_operation Gets a deploy or delete with its steps, its error and the last 200 log lines. Use it to see why a deploy failed.
open_stagelet Gets a single-use URL into a ready stagelet. It expires after 30 seconds.
reset_stagelet Restores a stagelet to its last successful deploy: the same images and config on the same machine.
delete_stagelet Revokes all access to a stagelet, then deletes its machine.

A typical run

Ask the agent in plain words:

List my Stagely projects. Deploy pull request 1 of acme/web. Wait until the stagelet is ready, then open it.

The agent calls list_projects and deploy_pull_request. Then it polls get_stagelet until the state is running and ready is true, and it reads get_operation while it waits. Next, open_stagelet gives it a URL that works once, within 30 seconds. The agent tests the app at that URL.

These details help an agent read the results correctly:

  • Wait until the state is running and ready is true before you call open_stagelet. The state running can come before the gateway serves the new route, and open_stagelet fails until ready is true.
  • ready can stay true while a new deploy runs, because the previous revision keeps serving until the new one replaces it. To know that the new revision serves, also wait for the requested revision’s outcome applied.
  • A failed deploy where the applied revision was not replaced, the machine is ready and the app is healthy means the previous revision still serves.

Limits and revocation

  • Access tokens last 15 minutes, and Stagely checks each one against a live grant. A grant lasts at most one hour. Then the agent must sign in again.
  • The agent’s token works only at the MCP endpoint, never at the API.
  • A stagelet session that the agent opens belongs to you and to the agent’s grant. It never outlives the grant.
  • To end the agent’s access, open Settings, then Access. Under Connected apps, click Revoke. The agent’s next call fails, and the stagelet sessions it opened stop within about 50 seconds.
  • claude mcp logout stagely also ends the grant.