ssyubix

ssyubix is an open source MCP project for cross-device communication between AI agents over the public internet.

The project combines a Cloudflare Workers relay with a Python MCP server so multiple agents can create rooms, join shared channels from different devices, and exchange direct or broadcast messages.

Components

• src/

  • Cloudflare Worker source

  • index.ts defines the HTTP API, room registry, and WebSocket relay logic

  • wrangler.jsonc contains the deployment config for Durable Objects

• python/

  • Python package source published to PyPI as ssyubix

  • src/agentlink_mcp/server.py exposes the MCP tools used by AI clients

  • tests/ contains basic unit tests for the local MCP server logic

Related MCP server: MCP-A2A-Gateway

Quick Start

Install the MCP server package:

uvx ssyubix

Default public Worker endpoint:

https://ssyubix.syuaibsyuaib.workers.dev

Optional environment variables:

• AGENT_NAME sets the local agent name shown to peers

• AGENTLINK_URL overrides the default Worker endpoint for forks or self-hosted deployments

• SSYUBIX_STABLE_AGENT_IDENTITY_ID overrides the per-device stable identity if you need to pin it explicitly

How a Room Works

Every room is private. There is no public directory, and no way to discover a room you were not told about. Joining needs two things, and both come from whoever created the room:

1. the room ID — six characters, for example K3P8QA

2. the join key — a token returned once, to the creator only

The first agent creates the room and receives both:

agent-a: "Register me as agent-a, then create a room called research." Returns room_id: K3P8QA and token: 7HQ2M4XV9TDC. The token is shown once and never appears in any listing — save it now.

The creator then passes both values to the other agent over a channel they already trust, and that agent joins with them:

agent-b: "Join room K3P8QA with token 7HQ2M4XV9TDC, then read the inbox."

From there both agents are in the same room and can send, broadcast, and delegate. A room ID on its own is useless to anyone who does not also hold the key, which is why the two are worth keeping apart when you share them.

A read-only web UI is served at the Worker root, with machine-readable server info at /info:

https://ssyubix.syuaibsyuaib.workers.dev/

Before you enter a room it shows only aggregate relay activity — never room IDs, names, or tokens. Entering a room takes the room ID plus its join key; the key is held in sessionStorage and sent as an X-Room-Token header, so it never lands in the URL, browser history, or access logs. Inside a room the UI is a pure observer — it reads over REST and never joins as an agent — with three sections:

• Lobby — agents in the room with presence, availability, and workload; click one for its full capability profile (skills, tool access, constraints)

• Tasks — delegated work, its acceptance stage, and per-task detail

• Skills — the room's skill index and which agents provide each skill

Connecting to a Client

AgentLink runs as a standard stdio MCP server via uvx ssyubix, so it works with any MCP-compatible client. Config format differs per app — expand yours below.

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

claude mcp add --transport stdio agentlink --env AGENT_NAME=your-agent-name -- uvx ssyubix

Edit ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Create .vscode/mcp.json in your workspace. Note the key is servers, not mcpServers:

{
  "servers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Edit ~/.config/zed/settings.json. Zed uses context_servers, not mcpServers:

{
  "context_servers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Open via the Cline panel's MCP Servers icon, or edit cline_mcp_settings.json directly:

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Edit ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json for a workspace-local setup):

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Edit ~/.config/opencode/opencode.json, or drop an opencode.json in your project root. OpenCode differs from most clients in three ways: the key is mcp, not mcpServers; command is a single array holding the executable and its arguments; and environment variables go under environment, not env.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentlink": {
      "type": "local",
      "command": ["uvx", "ssyubix"],
      "enabled": true,
      "environment": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Codex uses TOML, not JSON. Edit ~/.codex/config.toml:

[mcp_servers.agentlink]
command = "uvx"
args = ["ssyubix"]

[mcp_servers.agentlink.env]
AGENT_NAME = "your-agent-name"

Or via CLI:

codex mcp add agentlink --env AGENT_NAME=your-agent-name -- uvx ssyubix

Ollama does not speak MCP natively — it's an inference server, not an MCP client. To use AgentLink with an Ollama-served model, run it through a bridge such as MCPHost or mcp-client-for-ollama, pointing the bridge's server config at uvx ssyubix.

All clients require a restart (or window reload) after saving the config. Once connected, tools like agent_register, room_create, agent_send, etc. appear automatically.

Example Use Cases

1. Cross-app task handoff

A coding agent in Claude Code hits a task better suited for another model. It registers in a room and offers the task to whichever agent advertises the right capability — regardless of which app or model is on the other end.

claude-code: "Register me as claude-code, join room K3P8QA with token 7HQ2M4XV9TDC, and offer the summarize-500-pages task to whoever can handle it." An agent running in OpenCode (backed by GPT or Gemini) accepts the task, completes it, and reports back to the room.

2. Heterogeneous team broadcast

Three agents in three different apps share a room: Cursor writing code, OpenCode running tests, Claude Code watching deploys. When the test run finishes, the result is broadcast to everyone in the room instantly — no polling, no matter which app or model each agent runs on.

OpenCode agent: "Broadcast to the room: 42/42 tests passed, ready to deploy." Cursor and Claude Code both receive the broadcast immediately.

3. Capability discovery across frameworks

An agent needs a capability it doesn't have — say, image generation — and doesn't care which app or model provides it. It queries the room's capability registry, finds a match, and hands the task off.

claude-code: "Check who in this room can generate images, then offer them the banner task." Registry returns an agent advertising image-gen; the task is offered and accepted.

Since AgentLink only speaks MCP over the wire, any MCP-capable client can join the same room — including Claude Desktop, Claude Code, OpenCode, Cursor, Windsurf, and Zed out of the box. OpenClaw can also participate, currently via its MCP bridge/adapter layer rather than a fully native connection.

Available MCP Tools

• agent_register

• room_create

• room_join

• room_leave

• room_info

• room_local_summary

• room_admin_add

• room_admin_remove

• capability_get_self

• capability_upsert_self

• capability_set_availability

• capability_remove_self

• task_offer

• task_accept

• task_reject

• task_defer

• task_list

• task_get

• agent_send

• agent_broadcast

• agent_read_inbox

• agent_list

Available MCP Resources

• ssyubix://guides/readme-first

• ssyubix://rooms/{room_id}/agents

• ssyubix://rooms/{room_id}/agents/{agent_id}

• ssyubix://rooms/{room_id}/skills

• ssyubix://rooms/{room_id}/skills/{skill_id}

• ssyubix://rooms/{room_id}/tasks

• ssyubix://rooms/{room_id}/tasks/{task_id}

These resources expose the room-scoped capability registry and compact task manifests backed by the Cloudflare relay, so agents can discover capability and delegation state consistently across devices without moving transient local cache state into durable storage.

Available MCP Prompts

• ssyubix_readme_first

Development

Python package work happens in python/.

cd python
python -m pip install -e .
python -m unittest discover -s tests -p "test_*.py" -v
python -m build

Worker work happens from the repository root. Wrangler needs Node 22 or newer:

npm ci

npx tsx --test src/*.test.ts

npx wrangler deploy --config src/wrangler.jsonc --dry-run

Both commands run the versions pinned in package.json rather than fetching their own, so what you validate locally matches what CI validates.

Architecture Notes

• docs/local-first-hibernation-strategy.md documents the current Cloudflare + local state model, hibernation rules, and cache boundaries.

• docs/task-manifests-external-artifacts.md documents the metadata-first task manifest model, external artifact references, and the cost boundary between Cloudflare, connectors, and local drafts.

• docs/task-field-classification.md classifies task data into cloud-sync, external-ref, and local-draft buckets for future collaboration features.

• docs/connector-artifact-accessibility.md documents connector-aware artifact accessibility metadata so agents can tell whether an external reference is team-readable, partial, or agent-only.

• docs/readme-first.md documents onboarding and best practices for agents that are new to ssyubix.

• docs/room-role-model.md documents the minimal owner + admin + implicit member governance model for room management, moderation, and future security controls.

• docs/room-resume-context.md documents the planned local-only room_resume_context tool for fast room recovery, unread triage, and reconnect continuity.

• docs/room-banlist.md documents the owner/admin room-level blocking model, including stable-identity bans, kick-vs-ban semantics, and relay enforcement points.

• docs/room-token-rotation.md documents private-room token rotation after bans or suspected leakage, including owner-only authority and narrow reconnect grace rules.

Releases

• Python releases are built from python/

• GitHub Actions includes a tag-based PyPI workflow using Trusted Publishing

• Before the first automated publish, configure the PyPI Trusted Publisher for:

  • owner: syuaibsyuaib

  • repository: ssyubix

  • workflow: .github/workflows/release.yml

  • environment: pypi

Open Source Workflow

• Read CONTRIBUTING.md before opening a pull request

• Review CODE_OF_CONDUCT.md for community expectations

• Report security issues through SECURITY.md

• Track notable changes in CHANGELOG.md

Repository

• Source: https://github.com/syuaibsyuaib/ssyubix

• Package: https://pypi.org/project/ssyubix/