poema cloud

poema-mcp

poema-mcp, which the Python SDK installs, is an MCP server that lets Claude Code, or another MCP client, create and work in instances: it makes them, runs commands and edits files in them, suspends them when idle and forks them to try several approaches. It reads the same variables as the SDK. It is how an agent on your machine drives poema cloud, and not the MCP servers an agent running in an instance uses, which are set on New instance (Deploy from git). For Claude Code:

claude mcp add poema -e POEMA_URL=https://127.0.0.1:7070 -e POEMA_API_KEY=poema_ns_... -- poema-mcp

Claude Code has to find poema-mcp: put ~/.venvs/poema/bin on its PATH, or give the full path. Any other MCP client runs the same command, over stdio, with the same two variables.

Tools

  • sandbox_create makes a new instance and waits until it runs: a name, and optionally workspaces, a gateway and a model. It refuses a name an instance already has. Without a gateway an instance has no network; default reaches package registries and git hosts.
  • sandbox_run runs a shell command (bash -lc) to its end, in /workspace unless given a cwd, with no stdin, and returns its exit code and output. One still running after its timeout, 120 seconds unless given, is killed and returns its output so far.
  • sandbox_read_file and sandbox_write_file read and write a file, the write making its directories.
  • sandbox_list lists the instances and their phases.
  • sandbox_suspend suspends an instance: it stops using compute, and its memory and files are kept.
  • sandbox_resume wakes it and waits until it runs.
  • sandbox_fork forks an instance into new ones, 1 to 100 names, each running on a copy of its /workspace (with memory, of its memory too), and waits until they run. The instance is suspended first and stays so until resumed. Forks count toward the instances you may run at once.
  • sandbox_delete deletes an instance and its workspace.

A tool that fails answers with its error, for the client to act on.