Codex

Codex can use AgentServe as an MCP server or run the agentserve CLI in its shell. Either way, it can deploy a project, read its logs when something breaks, and hand you a claim link, all from the same session.

What you get#

• Five tools: deploy_stack, stack_status, get_logs, extend_ttl and destroy_stack. Each takes the project directory as path.
• Or the agentserve CLI, if you'd rather the agent run shell commands: deploy, status, logs, extend and destroy.
• Multi-service stacks from an agentserve.yaml, with URLs wired between services.
• Redeploys to the same URLs. The stack id and token are kept in .agentserve/stack.json in the project, shared with the CLI.

Set up with MCP#

You need uv. The MCP server runs on your machine over stdio, because it reads and packs your project directory; it deploys to https://agentserve.sh.

1. Add the server to config.toml#

   [mcp_servers.agentserve]
   command = "uvx"
   args = ["--from", "agentserve[mcp]", "agentserve-mcp"]
   # deploy_stack waits for the build; give it room
   tool_timeout_sec = 600

   uvx fetches the package on first start.

2. Check it#

   Start codex and run /mcp. agentserve should be listed with its five tools.

3. Tell Codex the rules (optional)#

   The tool descriptions cover the basics. For the manifest format, $DATA_DIR and what to tell you after a deploy, add the AgentServe skill to the project's AGENTS.md:

   curl -s https://agentserve.sh/skill.md >> AGENTS.md

Set up with the CLI#

Codex runs shell commands natively, so the agentserve CLI works without any MCP config. The one thing to sort out is network access, since deploy uploads to AgentServe.

1. Install the CLI#

   Put agentserve on your PATH, and check it installed:

   uv tool install agentserve
   agentserve --help

2. Let commands reach AgentServe#

   Codex's default sandbox blocks network access, so agentserve deploy would fail to connect. Allow it in the sandbox, or approve the command when Codex asks to run it outside:

   [sandbox_workspace_write]
   network_access = true

   Codex leaves variables with KEY, SECRET or TOKEN in the name out of commands by default, so an AGENTSERVE_API_KEY in your shell won't reach the CLI. To deploy into your account, pass it explicitly:

   [shell_environment_policy]
   set = { AGENTSERVE_API_KEY = "as_live_…" }

3. Tell Codex the rules#

   Append the skill to the project's AGENTS.md, as in step 3 above. Its examples are CLI commands, so Codex knows what to run.

The CLI and the MCP server share .agentserve/stack.json, so you can set up both and mix them: a stack deployed with one is redeployed by the other, at the same URLs. Every command is in the CLI reference.

A first prompt to try#

Build a tiny link shortener: a FastAPI service that stores links in SQLite under $DATA_DIR
and redirects /<code> to the target, plus a static page with a form. Deploy it with the
agentserve tools, passing this project's absolute path, and give me the URLs and the
claim link.

Codex should write an agentserve.yaml with two services, call deploy_stack, and reply with the URLs and the claim link. If the build fails, it should call get_logs with build set, fix the problem and deploy again.

Using the CLI? Ask for it "with the agentserve CLI"; Codex runs agentserve deploy and reads the URLs and claim link from the output.

How the claim link reaches you#

deploy_stack returns a claim_url, and Codex should give it to you along with the expiry time. Anonymous stacks run for 1 hour. Open the link, sign up or sign in, and the stack becomes yours at the same URLs, with its data. If it already expired, claiming restores it from the snapshot. See Claiming.

With the CLI, agentserve deploy prints the claim URL with the expiry, and agentserve status shows it again.

Missed it? It's saved as claim_url in .agentserve/stack.json in the project.

To skip the claim step entirely, add your key to the MCP server's environment in config.toml, and deploys go straight into your account with no clock:

env = { AGENTSERVE_API_KEY = "as_live_…" }

Troubleshooting#

• The server doesn't start. Run the command by hand: uvx --from 'agentserve[mcp]' agentserve-mcp. If uvx isn't found, set command to its absolute path (which uvx).
• Deploys time out but show up later. The build kept going on AgentServe. Raise tool_timeout_sec, then ask Codex to call stack_status. If no stack got linked, deploy again.
• The wrong directory got deployed, or "no stack linked to …". A relative path is resolved from wherever the MCP server was started, which may not be your project. Codex needs to pass the project's absolute path.
• Connection errors. Commands can't reach https://agentserve.sh. With the CLI, check network_access above; otherwise check your network or proxy settings.
• Result has deploy_error. The redeploy failed and the previous version is still serving. Logs first, then a fix.

More: Connect your agent, MCP tools, Manifest.