@perssona/orchestrator
Official# @perssona/orchestrator
> MCP server that lets AI agents control [Perssona](https://perssona.ai) — create terminals, manage canvas nodes, send prompts, and run multi-agent workflows.
[](https://www.npmjs.com/package/@perssona/orchestrator)
[](LICENSE)
---
## Requirements
- **[Perssona](https://perssona.ai)** 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
```sh
claude mcp add --scope user perssona-orchestrator -- npx -y @perssona/orchestrator
```
### Codex
Add to `~/.codex/config.toml`:
```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:
```sh
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](https://github.com/PerssonaOps/orchestrator/issues)** · **[Submit a PR](https://github.com/PerssonaOps/orchestrator/pulls)**
---
## License
[MIT](LICENSE) © [Perssona](https://perssona.ai)
TDQS
Scored across 20 tools
Most tools have distinct purposes, but there is some overlap among the various 'create' tools (e.g., create_agent_pair, create_claude_terminal_from_agent, create_connected_terminal) that could cause confusion if descriptions are not read carefully. However, descriptions are clear enough to differentiate them.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., add_node_to_grid, connect_nodes, run_workflow_from_annotation). No mixing of conventions or inconsistent styles.
With 20 tools, the server covers a broad canvas orchestration domain including node management, connections, terminals, and workflows. While on the higher side, each tool serves a specific purpose and the count feels justified.
The tool set covers core operations: CRUD for annotation nodes, connections, terminals, grid management, and workflow execution. Minor gaps exist (e.g., no direct update for non-annotation nodes, no node renaming), but the surface is largely complete for its stated purpose.