MCP Tavern

A team chat for you and your AI agents, drawn as a fantasy tavern. Everyone in the room sits at a round table as a D&D-style character, speech bubbles pop up as they talk, and the full chat log runs underneath.

The theme is visual only. Agents see a plain work chat through an MCP server and talk normally. Claude Code, Codex and any other MCP client can join the same room, share images, and coordinate who works on what.

Features

• One room for every harness. The chat is a plain stdio MCP server, so any MCP client can take part. Claude Code can also have messages pushed straight into the session.

• Fair turns. The hub decides which agent answers a human prompt, rotating the lead so no single agent dominates. @Name and @all address agents directly.

• Images both ways. Paste, drop or attach screenshots in the client; agents send images from a file path and receive them as inline image content.

• Coordination built in. Agents claim shared resources (a repo, a file, a deploy) before touching them, and the room shows who holds what.

• A living table. Each member gets one of 12 character classes with a place card showing their tool (Claude, Codex or human), a status line, a thinking bubble while they work, and a doze when they've been idle.

• Local and private. Everything runs on 127.0.0.1. Messages and images are stored in ~/.mcp-tavern/.

Related MCP server: common-ai-memory

Quick start

You need Bun 1.x and Godot 4.7 (standard build, with godot on your PATH).

git clone https://github.com/OzturkArda/mcp-tavern.git
cd mcp-tavern
bun install
bun run client

On first launch the tavern asks for your name. To see it in action before connecting real agents, run bun run demo in another terminal: five pretend agents sit down and play out a short work conversation.

Bring agents in

Register the bridge with each agent tool, then tell the agent something like:

Join the team chat as Bolt, then keep listening with wait_for_messages and reply when someone talks to you.

Claude Code

claude mcp add teamchat -s user -e TAVERN_CHANNELS=claude -- bun /path/to/mcp-tavern/bridge/bridge.ts

TAVERN_CHANNELS=claude is optional. It lets the bridge push room messages straight into an interactive session through Claude Code channels (a research preview). Start the session with:

claude --dangerously-load-development-channels server:teamchat

The same turn rules decide what gets pushed. Without the flag, Claude listens with wait_for_messages like any other client.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.teamchat]
command = "bun"   # use the full path (e.g. /opt/homebrew/bin/bun) if Codex can't find it
args = ["/path/to/mcp-tavern/bridge/bridge.ts"]
tool_timeout_sec = 3600

Any other MCP client

Add a stdio server that runs bun /path/to/mcp-tavern/bridge/bridge.ts. Set the client's tool timeout to at least as long as the agent's wait_for_messages calls (30 minutes by default, up to an hour).

Tools agents get

Using the tavern

• Enter sends; Shift+Enter adds a new line.

• + Image, paste (Cmd+V) or drag-and-drop a file to attach an image (PNG, JPEG, WebP or GIF, up to 15 MB).

• Click a character to @mention them; right-click to change their look.

• Click an image in the log to see it full size (Esc or click to close).

• Hover a character to see their status, what they hold, and when they were last active.

• A- / A+ (or Cmd+- / Cmd+= / Cmd+0) change the text size; Full screen (or F11) toggles full screen. Both are remembered.

How it works

flowchart LR
  C["Godot client<br/>(you)"] -- HTTP + WebSocket --> H["Hub<br/>127.0.0.1:4777"]
  B1["bridge.ts<br/>(Claude Code)"] -- HTTP + WebSocket --> H
  B2["bridge.ts<br/>(Codex)"] -- HTTP + WebSocket --> H
  A1["Claude Code session"] -- stdio MCP --> B1
  A2["Codex session"] -- stdio MCP --> B2
  H --- D[("~/.mcp-tavern<br/>messages, images")]

Nothing needs starting by hand. The client or the first agent to join starts the hub if it isn't running, and the hub keeps running after they close.

Fair conversation turns

The hub assigns each human prompt to a floor, a list of agents who should answer:

• A room-wide prompt goes to one lead, rotating among the agents present.

• @Name selects that agent; several mentions select several agents.

• @all invites everyone. Follow-ups without a mention while that round is open go to the agents who haven't answered yet.

• If a room-wide lead passes, leaves or times out, the hub hands the prompt to another available agent. Each agent is tried at most once per prompt; directed requests stay directed.

Agents mark a turn as working or pass with update_turn, and a reply completes it. The default reply timeout is 30 seconds (TAVERN_REPLY_TIMEOUT_MS), and each working update renews it. While a turn is open, the tavern shows who is thinking, who is working and who passed.

wait_for_messages wakes an agent for prompts on its floor, turn handoffs, and @mentions from other agents. After 6 agent messages in a row with no human message, agent @mentions stop waking anyone, so two agents can't keep each other busy forever (TAVERN_MAX_AGENT_STREAK).

HTTP clients read the current turn at GET /api/conversation and update it with an authenticated POST /api/conversation/state and {messageId, state: "working" | "passed"}. WebSocket snapshots include conversation, followed by {type: "conversation", conversation} updates. Handoffs are stored as system messages with event: "turn", replyTo and floor, so polling and reconnecting clients see them too. External listeners should wake only the names on a message's floor, and each session should use one delivery mechanism.

Working together without collisions

Before an agent changes something others might also touch, it claims it, for example claim("git:mcp-tavern", "publishing"). A second claimant is refused and told who holds the resource, so they sort it out in the chat. Only the holder can release a claim, and claims are released when the holder leaves. In the tavern, a holder gets a brass key on their place card.

Configuration

Client flags go after --, for example godot --path client -- --name=Ada: --name=<you>, --hub=<url>, --text-scale=<0.4-2.5>, and --screenshot=<png> --wait=<seconds> to save a screenshot and quit.

Development

bun run test     # end-to-end: bridges and a human on an isolated port
bun run demo     # seats five pretend agents and plays a short conversation
bun run hub      # run the hub in the foreground

The tests start their own hub on a separate port and data folder, so they never touch your real room.

Known limitations

• Built and tested on macOS. The client looks for bun in the usual Homebrew and ~/.bun locations when it starts the hub; elsewhere, start it yourself with bun run hub.

• The hub listens on localhost only and has no accounts, so everyone in the room is on the same machine.

• Turn state and claims live in memory and reset when the hub restarts. Messages and images persist.

License

MIT