MCP server
The Screenplay MCP server connects an AI assistant to a Screenplay application: a
folder of .play files. The assistant can answer questions about
the model, draw it as an event model board, propose edits and, once you approve
one, write it. It is part of the screenplay tool, runs locally over standard
input and output, and makes no network calls of its own.
You talk to the assistant in your own words. The assistant calls the server’s tools; you never type a tool call. The guides here are written as prompts you can paste into Claude Code, Codex, VS Code or Claude Desktop.
What it can do
Section titled “What it can do”| You want to | Start with |
|---|---|
| Connect Claude Code, Codex, VS Code or Claude Desktop | Install the MCP server |
| Create a Screenplay model from a description | Create a model |
| Ask what a model contains and how its parts connect | Explore a model |
| See the model as an event model board | View a model |
| Change, rename, move and repair parts of a model | Edit a model |
How changes stay safe
Section titled “How changes stay safe”Reading is free. Writing is deliberate and happens in three steps:
- Propose. The assistant describes an edit. The server checks it against the
exact snapshot it was made from and returns a
proposalId. Nothing is written. - Review. You, or the assistant on your behalf, read the exact before and after bytes, the comments a change would drop and whether the result still compiles.
- Apply. Only
applyandrecover-workspacechange files. Keep your client’s approval prompt on for both.
A proposal is bound to one revision of the model. If a file changes on disk, or another proposal is applied first, the stale proposal is rejected rather than merged. Ask the assistant to reopen the model and propose again.
Where the model lives
Section titled “Where the model lives”The server root is the application boundary: one folder is one application, however
many files and nested features it holds. The .play files stay canonical source;
the server adds a reserved .screenplay/ folder next to them with stable
identities. See identity state and recovery.
For tool authors and hosts
Section titled “For tool authors and hosts”These pages describe the server’s tools directly, for people building a client or a host, or debugging what an assistant did:
- Authoring with the MCP tools walks through the typed
propose-astworkflow with complete tool arguments. - Identity state and recovery explains
.screenplay/, interrupted applies and explicit rollback. - MCP reference lists every tool, argument, limit and the embedding API.