Plug any agent into a Huddle session.

What is MCP?

MCP (Model Context Protocol) is an open protocol for giving agents structured access to tools and resources. Instead of pasting a file into a chat and asking an agent to reason about it, the client connects to an MCP server and the agent can actually open the file, read from it, and write back. Claude Code, Cursor, Gemini CLI, Codex CLI, Continue, Windsurf, and Zed all speak MCP.

The Huddle MCP server

The @huddle/mcp package is a standalone server that exposes Huddle sessions over MCP. Once installed, your agent can join a session, list the files, read and write them (respecting the CRDT so humans in the session see the edits live), hold locks, chat with other participants, and check the session budget.

It ships fourteen v1 tools and five resources — enough for an agent to work as an equal participant in a pair-programming session. Transport is stdio today, with HTTP streamable coming in the next release.

Install for your client

The package is published to npm, so every client has the same one-line install:

# Claude Code
claude mcp add huddle -- npx -y @huddle/mcp

# Gemini CLI
gemini mcp add huddle -- npx -y @huddle/mcp

# Codex CLI
codex mcp add huddle -- npx -y @huddle/mcp

For Cursor, Continue, Zed, and Windsurf, drop the following into your MCP config file (the exact path varies by client — check your client's docs):

{
  "mcpServers": {
    "huddle": {
      "command": "npx",
      "args": ["-y", "@huddle/mcp"]
    }
  }
}

Authenticating

The first time you invoke a Huddle tool, the MCP server runs the CLI login flow: it opens your browser, you sign in to Huddle, and the resulting credentials are stored in your OS keychain (or ~/.huddle/credentials.json as a fallback). Nothing is ever read from an environment variable unless you opt in.

For local development against a workspace build:

claude mcp add huddle \
  --env HUDDLE_API_URL=http://localhost:4000 \
  --env HUDDLE_SYNC_URL=ws://localhost:4100 \
  --env HUDDLE_DEV_EMAIL=me@test.local \
  -- node /absolute/path/to/huddle/packages/mcp-server/dist/server.js

With HUDDLE_DEV_EMAIL set the server will auto-provision a dev token via the internal dev-login endpoint, so you never have to hit the browser flow.

Available tools

The v1 toolset covers the full pair-programming loop:

• huddle_join_session / huddle_leave_session — attach and detach from a session.
• huddle_list_files / huddle_read_file / huddle_write_file — navigate and edit the project tree.
• huddle_acquire_lock / huddle_release_lock — coordinate with humans to avoid stepping on active edits.
• huddle_read_plan / huddle_update_plan — read and revise the session's shared plan document.
• huddle_claim_task / huddle_complete_task — mark work in flight and wrap it up.
• huddle_say — post a message to session chat.
• huddle_check_budget — query remaining token budget before a long call.

Resources let the agent introspect the session without calling a tool: huddle://session/current, huddle://memory/team, huddle://plan, huddle://participants, huddle://events/recent.

Once the agent has joined a session with huddle_join_session, every subsequent tool call auto-injects the session id — the agent does not have to remember it. Returning to the concepts page is a good next read if you want the mental model for why sessions work this way.