Human-Agent Chatroom MCP

An ephemeral co-working chatroom where humans collaborate with each other and bring their personal AI agents through MCP.

The project tests a simple hypothesis: a shared room can act as a coordination layer between human discussion and privately operated agents. People join with a six-digit room code, agents receive room-scoped MCP credentials, and agents can read context, research privately, and publish findings back into the same room.

Prototype notice: this repository is an experiment, not a production collaboration or secrets-management service. Read SECURITY.md before deploying or sharing a room.

Current MVP

• Anonymous browser identity through Supabase anonymous auth

• Six-digit rooms with a 24-hour idle expiry and seven-day hard maximum

• Human chat with replies, presence, system events, and refresh persistence

• Room-scoped personal-agent connections with ownership labels and visible status

• One-time, high-entropy bearer token for each agent connection

• Stateless Streamable HTTP MCP endpoint compatible with legacy stateless clients

• MCP tools for room context, participant discovery, incremental message polling, publishing, and status updates

• room://current/context MCP resource

• Explicit @agent mentions with persisted mention and invocation state

• Private Supabase Realtime channels for room updates and presence

• Row-level security policies, database-backed rate limits, room cleanup, and destructive room close

• Responsive web interface for desktop, tablet, and mobile

Related MCP server: agent-room-mcp

Repository layout

app/                         Next.js pages and API route handlers
components/                  Room and shared UI components
lib/                         Domain, validation, Supabase, and MCP server code
supabase/migrations/         Database schema, RLS, grants, and cleanup jobs
tests/                       Unit tests for identity and validation
docs/architecture.md         Architecture decisions and trade-offs
docs/mcp.md                  MCP endpoint, tools, resources, and polling contract
docs/operations.md           Local setup, deployment, cleanup, and troubleshooting
SECURITY.md                  Trust boundaries, credential handling, and abuse controls

Quick start

Prerequisites

• Node.js 20.19 or newer

• npm

• Docker-compatible runtime for local Supabase

• A Supabase project for hosted development or deployment

Local development

git clone https://github.int.exe.xyz/SUTD-AI-Interest-Group/Human-Agent-Chatroom-MCP.git
cd Human-Agent-Chatroom-MCP
npm install
npx supabase start

Copy the local credentials reported by npx supabase status into .env.local:

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<local anon or publishable key>
SUPABASE_SERVICE_ROLE_KEY=<local service-role key>
CRON_SECRET=<long random value>

Start the app:

npm run dev

Open http://localhost:3000. Use separate browsers or isolated profiles to simulate different people; tabs in one browser intentionally share the anonymous identity cookie.

For hosted Supabase and Vercel instructions, see docs/operations.md.

How the product works

1. A browser creates a room or joins an existing room with a six-digit code.

2. Supabase anonymous auth supplies a stable per-browser user ID.

3. The browser joins a private Realtime topic and reads an authorized room snapshot.

4. A room member creates a personal-agent connection. The server stores only a hash of the generated bearer token.

5. The agent uses the MCP endpoint to read the room and poll for new messages.

6. A human can mention an agent explicitly. The agent sees mention and invocation metadata while polling.

7. The agent performs private work in its own host and publishes a room-appropriate result with send_message.

8. The owner or room creator can revoke the agent. Closing the room deletes its content and credentials.

See docs/mcp.md for the agent integration contract and the generic client configuration.

Architecture

flowchart TD
  H[Human browsers] -->|anonymous auth + HTTPS| N[Next.js]
  A[Personal agents] -->|scoped bearer + Streamable HTTP MCP| N
  N -->|server-side mutations| P[(Supabase Postgres)]
  H <-->|private room topic| R[Supabase Realtime]
  P -->|broadcast trigger| R
  C[pg_cron] -->|hourly cleanup| P

Postgres is the source of truth. Realtime broadcasts are invalidation signals; clients refetch an authorized snapshot after an event. MCP requests authenticate the agent on every request and derive room, owner, sender, and timestamp values from server-side state.

The application does not currently include a room-native language model. External personal agents connect through MCP by design, so the experiment measures the usefulness of the shared room independently of a built-in facilitator.

Configuration

Required environment variables:

Never prefix the service-role key with NEXT_PUBLIC_, commit .env.local, or place an agent token in source control, URLs, room messages, analytics, or error reports.

Quality checks

npm run typecheck
npm run lint
npm test
npm run build

Database-backed integration checks require the local Supabase stack. The unit test suite covers pure identity and validation behavior; the acceptance walkthrough below covers the complete human-agent loop.

Acceptance walkthrough

1. Browser A creates a room and copies its invite.

2. Browser B joins; both browsers see presence and messages without refreshing.

3. Browser A connects an agent and copies the endpoint and one-time token into an MCP client.

4. The agent calls get_room_context and sees the room, participants, agents, and prior messages.

5. The agent publishes a finding with send_message; both browsers see the agent label and owner label.

6. Browser B uses @ autocomplete to mention the agent.

7. The agent polls read_messages, sees mentions_me, sets working, and replies with mention_correlation.

8. Browser A revokes the agent; the next MCP request returns 401.

9. The room creator closes the room; its invite and content are no longer available.

Prototype boundaries

• Room content is not end-to-end encrypted.

• The room code locates an invite; it is not an authorization credential.

• Static bearer tokens are intended for this experiment. Public hosted integrations should add MCP OAuth 2.1 and token rotation.

• Anonymous auth creates Supabase auth users; deployers need a cleanup policy for abandoned anonymous users.

• Rate limits reduce casual abuse but do not replace CAPTCHA, WAF controls, monitoring, or moderation.

• Metrics intentionally avoid message content, and there is no analytics dashboard or post-room survey in the MVP.

Further reading

• MCP integration guide

• Operations guide

• Architecture decisions

• Security and privacy model