Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cohort MCP Server Find a project seeking a designer, open its room, and post a quick hello."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Skip to the content
Find your cohort. Build your company.
Cohort is one of the seven tools of Topsoil Commons. It serves Layer 3, belonging.
First step: click Browse projects in the app, pick a project that fits, and open its workspace to meet the builders there. To run the app on your own machine, follow the quick start in the section for agents and builders at the end of this page.
What runs today: a community site in this repo, with a projects board, shared rooms, and a live workspace. A program can join a room as a member and work next to the people there. A recording of a live session with a program member is in this repo as proof, and the test suite passes 7 of 7. There are no accounts yet: you pick a name and you are in. What is verified, and what is still limited, is stated in full in the section for agents and builders at the end of this page.
You do not need to apply. No one takes a share of your company. The code is free under the MIT license. Anyone can run a copy, change it, and share the change.
This repo serves Layer 3: Belonging.
"People who know your name. A room where your work is seen. A first believer when you are starting from nothing." Cohort makes that room the internet, where builders meet, form teams, and start working together in a live workspace.
Unmet, it looks like: loneliness at scale, builders and neighbors invisible to each other, communities that exist only as audiences for someone else's platform.
The full map: The Ascent, a map of human needs
Related MCP server: Roblox Studio MCP
Projects board: pitch an idea in one breath, tag the roles you're looking for, and let the community find you.
Real-time workspace: every project gets a shared live-editing document and a group chat, kept in step for everyone at once.
AI co-builder: bring your own API key (Gemini, Groq, OpenRouter,
Anthropic, or any OpenAI-compatible endpoint) and prompt the AI together
with your cofounders using @ai in chat. Replies go to the whole room.
Upvotes and leaderboard: back the projects you believe in; the projects with the most votes are shown first.
Live Hacker News feed: the top 30 stories, fetched and stored by the server for a short time, so members can see what builders are talking about now.
Cohort never stores your AI key on the server. It lives in your browser's
localStorage and is forwarded only with your own @ai requests, used
transiently for the outbound provider call. Configure it via AI Settings
in the top nav.
Provider | Free tier (approx.) | Get a key |
Gemini | ~1,500 requests/day | |
Groq | ~1,000 requests/day | |
OpenRouter | free-tier models | |
Anthropic | pay-as-you-go |
Any OpenAI-compatible endpoint also works via the Custom base URL provider.
Cohort is Act 2, the Commons, in a five part body of work built on one thesis: technology should increase human capability without taking human agency away. The problem family this act serves is collective action and coordination failure: good people with good ideas who never find each other. The other acts:
Act 1, the Atlas: atlas, how people learn.
Act 3, the Machine: machine, how the machine itself learns, from first principles.
Act 4, the Graph: graph, how knowledge connects and can be questioned.
Act 5, the Guardrails: lumen, how all of it stays safe, cited, and human governed.
The north star metric for this act, counted honestly once the commons is live and dated when reported: builders who shipped something real in a cohort room. No number is claimed yet, because there are no public rooms yet. Ways to take part, including sized tasks for partners and contributors, are in the guide to taking part and the guide to contributing.
Live demo: https://topsoilcommons.github.io/cohort/
That page shows this README as a web page. The working app is not hosted there. To use the app, follow the quick start in the section for agents and builders below and open the site it starts.
The exact technical description lives in this section. Everything a person needs is stated in plain words above it.
npm install
node server.jsThen open http://localhost:3000.
State lives in a single data.json file next to the server (auto-created and
seeded with demo projects on first boot; gitignored).
The whole server is one file, server.js (about 600 lines, Express plus the
ws WebSocket library), and that is a deliberate choice: the project is small
enough that one readable file beats a framework. It serves:
A REST API for projects: list, create, adopt, and upvote, with input length limits enforced on every field.
WebSocket rooms, one per project, carrying the shared document and the room chat. Document sync is last write wins (see limitations below).
An @ai chat endpoint that proxies to whichever provider the user
configured, using the user's own key.
Cached proxies for the Hacker News and open-source feeds, so the board stays fast and the upstream APIs stay unhammered.
Persistence is a single data.json with debounced saves. It is honest
single-instance storage: run one server process and it is exactly right;
run five and it is exactly wrong. For a community tool at this scale, that
trade is stated rather than hidden.
Cohort ships an MCP server (mcp-server.js) that lets an external AI agent
work in a room alongside the humans. It is a real client of the workspace,
not a backdoor: it reads projects through the REST API and joins rooms over
WebSocket under its own handle (agent by default), so everything it does
is visible in the room. Seven tools: list and get projects, read full room
state (project, shared document, recent chat, presence) in one call, post
chat, update the document, create a project, upvote. Every tool declares an
output schema and returns structured content an agent can plan over, and
errors come back with machine readable codes. The REST endpoints it uses are GET and POST /api/projects, GET /api/projects/:id, POST /api/projects/adopt, POST /api/projects/:id/upvote, GET /api/opensource, and GET /api/news, with WebSocket rooms keyed by project id.
Verified like everything else here: the automated suite (npm test, 7
tests) drives the MCP server over stdio through a real handshake and tool
calls, and a recorded session transcript lives at
test/evidence/mcp-session.json. Run it yourself:
node server.js # in one terminal
npm run demo:mcp # records a fresh session transcriptAgent task history in room state (shipped October 16, 2026). Every
room now keeps an activity log: project created or adopted, upvotes, chat
messages, document updates, and AI requests and replies, each with the
actor and the time. It rides in the room state an agent reads first
(get_room_state), stands on its own in the get_task_history MCP tool,
and is returned by GET /api/projects/:id. Multi session work has memory.
Scoped agent identities (planned). The MCP server currently acts under
one configured handle because Cohort has no auth model yet. When it gets
one, agents get identities of their own, scoped and auditable. This is
the same authorization problem the wider MCP field is working on; see
docs/LANDSCAPE.md.
Auth model (decided October 16, 2026, not yet implemented). The decision is recorded in docs/AUTH.md: scoped token identities, a named operator on every agent token, and no full account system until there is a hosted instance. No auth is shipped yet; handles are still self claimed, as the status section below states.
Yjs CRDT editor: replace the naive last-write-wins textarea sync with real conflict-free collaborative editing.
CodeMirror: syntax highlighting and a proper editing surface in the shared workspace.
Founder profiles: skills, timezone, track record, past cohorts.
Demo days: scheduled community showcases with live voting.
Age-gated tracks: a safe, moderated track for young builders.
Working and verified: the server boots clean, the projects API returns the seeded board, workspaces sync in real time, the AI co-builder works with any of the providers below, the MCP server passes its protocol tests, and the REST API is covered by automated tests. Known limitations, stated plainly:
No accounts or auth. Handles are self claimed. Fine for an open community demo, not fine for anything private.
Document sync is last write wins. Two people typing in the same paragraph at the same moment can overwrite each other. A CRDT editor is the first item on the roadmap.
Single instance persistence. data.json will not survive a
multi-instance host. A real database is the obvious next step when a
deployment outgrows one process.
The server in this repo can run as a public demo at no cost. The package is ready (a Dockerfile, a Render blueprint in render.yaml, and a server that reads its port from the PORT environment variable). One step needs a person, because it creates an account in your name:
Go to render.com and sign up with your GitHub account. This package targets the free plan. If signup ever asks for a card, stop there; the free route should not, and the Dockerfile route below works on any host.
Choose New, then Blueprint, and pick this repository. Render reads render.yaml and fills in the build and start commands itself.
Confirm the free plan and create the service. Render builds it and gives it an onrender.com address. Open that address and the app answers with its demo data.
Any host that runs the Dockerfile works the same way.
The limits, stated plainly:
It sleeps. A free service stops after about 15 minutes without visitors and takes about a minute to wake for the next one.
Its memory is temporary. The data file lives on a disk the host can wipe, so the app reseeds its demo data when it restarts. Nothing real should be stored in a demo instance.
It is one small process. Enough to open, use, and judge the app. Not a production home for a real community.
Pick a good first issue in this repo, sized in hours and written to be finishable by a newcomer. Take the Eval Challenge against this repo's published session and test results, and submit your run. Report adoption from real use, good or bad, with evidence of what happened.
The full protocol: The Open Table. Verified work is credited in the public Ledger.
Prompt A, for an AI agent:
You are an AI agent taking the Eval Challenge in the cohort repo.
Start from a clean state with no local data.json, then run npm ci and npm test.
Compare your result with the published baseline: seven tests pass out of seven, made of six REST API tests plus one MCP protocol test, and the MCP server offers seven tools.
Then start the server with node server.js and run npm run demo:mcp, and compare the fresh transcript with the recorded session at test/evidence/mcp-session.json.
Attach the full run to your submission, keep to one improvement per pull request, state that you are an agent, and name your operator.Prompt B, for a human:
File a failure report using the failure report template in this repo.
Include the input you used, what happened, and what should have happened.
Attach the run, transcript, or output that shows the failure, if you have one.MIT. See LICENSE. Copyright (c) 2026 Cohort contributors.
Express, ws, Hacker News API (Y Combinator), the OpenAI-compatible chat completions convention adopted by Google, Groq and OpenRouter, and the Y Combinator ethos of make something people want, which this project tries to give away for free.
This server cannot be deployed
Project management for AI agents: tasks, docs, decisions and time in one shared team context.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.