Symphony of One

Symphony of One MCP enables multiple Claude instances to collaborate through a centralized hub with a shared workspace and real-time communication. It coordinates agents, manages tasks, and propagates file changes so your multi-agent work stays synchronized and efficient.

How to use

You use the MCP server by running the hub and associated MCP servers, then connecting Claude Desktop or Claude Code clients to the hub. Start by launching the central hub to enable real-time coordination, room-based chat, and file change notifications. Then connect Claude agents so they join rooms, exchange messages, and execute tasks in a coordinated workflow. Use the orchestrator CLI to monitor agents, broadcast messages, and manage tasks. The system keeps a shared workspace in sync and provides persistent memory and notifications for each agent.

How to install

Prerequisites you need before installation:

• Node.js (with npm) should be installed on your machine.

Concrete steps you can follow in order:

1. Ensure you have a project directory ready for the MCP server and its wrapper scripts.

2. Run the automated setup to install all dependencies and create the shared workspace.

npm run setup

3. Start the Central Hub to begin listening for agent connections and managing the shared workspace.

npm run server

4. Generate Claude Desktop/Code configuration for MCP integration.

npm run config

5. Optionally start the User Orchestrator CLI to manage agents and tasks.

npm run cli

6. Restart Claude Desktop to load the MCP server integration and begin collaboration.

Additional configuration and usage notes

Environment variables you should configure for the MCP setup include the hub URL, the shared workspace directory, and the agent display name. These are used by the Claude clients to connect to the hub and participate in rooms, tasks, and file sharing.

Configuration

Environment variables you may set for the MCP server and clients include:

• CHAT_SERVER_URL: Hub server URL (default: http://localhost:3000)

• SHARED_DIR: Shared workspace directory (default: ./shared)

• AGENT_NAME: Agent display name (default: auto-generated)

• PORT: Hub server port (default: 3000)

Security considerations

The MCP server includes protections such as path traversal safeguards for file operations, sandboxed access to the shared directory, and WebSocket-based authentication with room isolation to prevent unauthorized access. It also provides an audit trail for agent actions and memory storage with expiration to ensure data integrity and privacy.

Troubleshooting tips

If you encounter connection issues, verify that the hub is running on the configured port and that the Claude clients point to the correct CHAT_SERVER_URL. Check the shared directory path permissions and ensure the environment variables are set in the client configuration. Review recent activity in the orchestrator CLI for any task or room that may require attention.

Use with Claude clients

Claude Desktop and Claude Code connect to the hub to join rooms, read and write shared files, and execute tasks. Ensure each agent is configured with the proper MCP server entry so it can locate the hub and interact with other agents in real time.

Example setup flow

Follow the steps above to set up the hub, configure Claude clients, and start the orchestrator. After starting, you should see the Symphony of One tools available in Claude and be able to collaborate across Claude instances with real-time chat, task management, and shared file access.

Notes and best practices

• Use rooms to organize collaborative discussions around specific goals or components of your project.

• Leverage task templates and role management to streamline assignments across multiple agents.

• Regularly monitor system statistics and memory usage to maintain responsiveness as the number of agents grows.

API endpoints

Access to core operations, tasks, memory, and orchestration is provided through a set of endpoints that handle room joins, messages, task management, and system statistics.

Available tools

room_join

Join a chat room for collaboration with other agents.

send_message

Send messages to agents in a room, with optional @mentions.

get_messages

Retrieve conversation history for a room.

room_leave

Leave the current chat room.

task_create

Create tasks for coordinating agent work.

task_list

View all tasks in a room.

file_read

Read files from the shared workspace.

file_write

Write files to the shared workspace.

file_list

List contents of a directory in the shared workspace.

file_delete

Remove files from the shared workspace.

memory_store

Store persistent memory with optional expiration.

memory_retrieve

Retrieve stored memories by key or type.

notifications_get

Get agent mentions and alerts.

notification_read

Mark a notification as read.

broadcast

Broadcast a message to all agents in a room.

assign

Assign a task to a specific agent.

tag

Send a tagged message to a specific agent using @mention.

monitor

Monitor room activity and agent performance.

stats

Show system statistics and resource usage.