@perssona/orchestrator

MCP server that lets AI agents control Perssona — create terminals, manage canvas nodes, send prompts, and run multi-agent workflows.

---

Requirements

• Perssona must be running — the MCP communicates with the local bridge on 127.0.0.1:17381
• Node.js 18+
• Claude Code or Codex CLI

---

Installation

Claude Code

claude mcp add --scope user perssona-orchestrator -- npx -y @perssona/orchestrator

Codex

Add to ~/.codex/config.toml:

[mcp_servers.perssona-orchestrator]
command = "npx"
args = ["-y", "@perssona/orchestrator"]
startup_timeout_sec = 60

---

Available Tools

Tool	Description
create_connected_terminal	Create a terminal node connected to a source node
create_codex_terminal_from_agent	Create a Codex terminal from an agent preset
create_claude_terminal_from_agent	Create a Claude terminal from an agent preset
create_agent_pair	Create two connected LLM terminals for parallel roles
run_workflow_from_annotation	Run a multi-agent workflow from an annotation or prompt
send_text_to_terminal	Send text directly to a specific terminal node
send_text_to_connected_terminals	Broadcast text to all terminals connected to a node
send_annotation_to_connected_terminals	Send annotation content to connected terminals
create_annotation_node	Create an annotation node on the canvas
update_annotation_node	Update an existing annotation node
connect_nodes	Connect two canvas nodes with an edge
disconnect_nodes	Remove the edge between two nodes
remove_node	Remove a node and its edges
focus_node	Select and center the viewport on a node
add_node_to_grid	Add a node to the grid view
open_nodes_in_grid	Open one or more nodes in the grid view
get_selected_node	Return the currently selected canvas node
get_connected_nodes	Return nodes connected to a given node
list_canvas_nodes	List all nodes and edges in the active canvas
list_orchestrator_presets	List workspace presets (models, agents, workflows)

---

Debug

Set PERSSONA_MCP_DEBUG=1 to write a log to your system temp directory:

PERSSONA_MCP_DEBUG=1 node server.mjs

---

Contributing

Contributions are welcome via Pull Requests.

• The main branch is protected — direct pushes are not allowed
• Open an issue first for bugs or feature proposals
• Keep PRs focused and well-described

Open an issue · Submit a PR

---

License

MIT © Perssona