Skip to content
screenjson

screenjson-server

Have a team of agents edit a library over MCP

Connect several Claude sessions to screenjson-server, each with its own token, and let them edit the same scripts at once without overwriting each other.

Last updated September 2026

screenjson-server’s /mcp endpoint turns the library into tools an agent can call: read an outline, read a scene, edit a line, insert a scene, search. Every call goes through the same API as a human editor’s, so several agents can work on the same scripts at once and the server keeps them honest.

1. One token per agent

A token names who made each change and who holds each checkout. Give every agent its own:

S=http://127.0.0.1:8080
for name in dialogue-polish continuity props; do
  curl -s -X POST $S/tokens -d "{\"name\":\"$name\"}" | jq -r .token > "$name.token"
done

2. Connect each agent

In each Claude Code session (or project), add the server with that agent’s token:

claude mcp add --transport http screenjson $S/mcp \
  --header "Authorization: Bearer $(cat dialogue-polish.token)"

For Claude Desktop, Cursor and other clients, the same thing as JSON:

{
  "mcpServers": {
    "screenjson": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

3. Give each one a job

The agents don’t need to know about each other. Brief them on their own task:

  • dialogue-polish: “In The Heist, tighten every line of MARA’s dialogue in Act II. Read each scene with read_scene before editing it.”
  • continuity: “Check every scene heading in The Heist for consistent locations and times of day, and fix the sluglines with edit_scene_heading.”
  • props: “For every scene in The Heist, add the props mentioned in the action lines to the scene’s props list.”

What keeps them from colliding

  • Revisions. Every line has a revision number. When an agent edits a line that another agent changed since it read it, the server refuses with 412, and the agent reads the line again before retrying. No change is silently lost.
  • Checkouts. An agent about to rework a whole scene can call checkout on it. Until it calls release (or the checkout expires, five minutes by default), other tokens get 423 when they try to change that scene.
  • Validation. Every write is checked against the ScreenJSON schema. An agent can’t leave a script half-broken.
  • One queue per script. Writes to a script are applied one at a time, in order, so concurrent edits to different lines all land.

4. Watch it happen

Open the script in the server’s web app (http://127.0.0.1:8080/#/d/<id>) while the agents work: each edit appears as it lands, and each change in the event stream carries the actor, the agent’s token name. See Watch a script change live to follow the same stream from code.

Next