@collhub/mcp connects an MCP host — Claude Code, Claude Desktop, Cursor, VS Code, Codex — to your CollHub instance. The assistant can then search and read your documents, write and edit them, comment, run projects and tasks, move documents through workflows, follow relationships, query data sources and talk to CollHub's own chat threads.

The server runs on your machine and talks to the host over stdio. Its only configuration is the URL of your instance; you sign in with your browser, and no password is stored anywhere.

Requirements

Node.js 22.19 or later — node --version tells you which one you have.
The URL of your CollHub instance, for example https://acme.collhub.com.
A CollHub account on that instance.

Install

Every host launches the server the same way: npx -y @collhub/mcp with the instance URL in COLLHUB_URL. Replace https://acme.collhub.com below with your own instance.

Claude Code

claude mcp add -s user collhub -e COLLHUB_URL=https://acme.collhub.com -- npx -y @collhub/mcp

-s user makes the server available in every project; -s project registers it for the current project only, in its .mcp.json.

Claude Desktop

Settings → Developer → Edit Config, then add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "collhub": {
      "command": "npx",
      "args": ["-y", "@collhub/mcp"],
      "env": { "COLLHUB_URL": "https://acme.collhub.com" }
    }
  }
}

Cursor

In .cursor/mcp.json (one project) or ~/.cursor/mcp.json (everywhere):

{
  "mcpServers": {
    "collhub": {
      "command": "npx",
      "args": ["-y", "@collhub/mcp"],
      "env": { "COLLHUB_URL": "https://acme.collhub.com" }
    }
  }
}

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "collhub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@collhub/mcp"],
      "env": { "COLLHUB_URL": "https://acme.collhub.com" }
    }
  }
}

Codex

In ~/.codex/config.toml:

[mcp_servers.collhub]
command = "npx"
args = ["-y", "@collhub/mcp"]

[mcp_servers.collhub.env]
COLLHUB_URL = "https://acme.collhub.com"

Signing in

The first time a host connects, the server opens your browser on the CollHub login and consent page (it also prints the URL on stderr, which the host shows in its MCP log). Once you approve, a refresh token stored on this machine keeps the session alive — under ~/.config/collhub-mcp/sessions/ (or $XDG_CONFIG_HOME/collhub-mcp), one file per instance and host, readable by you only. Claude Code, Claude Desktop, Cursor and Codex each sign in once and then keep their own session.

Who am I, sign out, switch account. Ask the assistant: whoami says who the server is signed in as, logout ends the session on this host only, and login with switch user signs the browser out first so you can enter a different account. Without an assistant, delete the session file and reconnect.
Headless machines (SSH sessions, containers, build agents). There is no password path. From a machine with a browser, forward one of the ports the login uses — ssh -L 52180:127.0.0.1:52180 <host> — then open the URL the server prints.
What the assistant sees. Sessions opened this way are classified by CollHub as an AI agent. A document whose access rules block AI actors is invisible to the assistant even though you see it in the app.

Several instances

To reach more than one CollHub instance from a single server, configure COLLHUB_INSTANCES instead of COLLHUB_URL:

[
  { "name": "prod", "url": "https://acme.collhub.com" },
  { "name": "staging", "url": "https://staging.acme.collhub.com" }
]

(as one JSON string in the host's env). Each instance gets its own sign-in and its own stored session. Every tool then takes an optional instance argument naming the target, and a list_instances tool lists them; a call that omits it goes to the first instance. Routing is per call — there is no "current instance" that one conversation could switch under another.

Configuration

Variable	Description
`COLLHUB_URL`	The instance URL (single-instance mode)
`COLLHUB_INSTANCES`	JSON array of `{name, url}` objects (multi-instance mode)
`COLLHUB_PROFILE`	Overrides the host name that keys the stored session (default: the connecting host's name)

What the assistant can do

Documents — search (keyword, semantic and hybrid), read whole documents or single sections, write, edit in place, create, upload, rename, move, version history and diffs
Collections and folders — browse, create, metadata schemas
Projects — create from a template, read and update the project graph in one call, tasks, trackers and milestones
Comments — list, add, resolve
Relationships — the typed links between documents
Metadata and labels — update fields, manage labels
Workflows — enter, advance and exit document lifecycles
Data sources — query and modify tabular data
Threads — list CollHub chat threads, read them, send messages and wait for the reply

On connect the server also hands the host a short guide to working with CollHub — how documents are addressed, how edits are made, how projects are laid out — so the assistant knows the house rules before its first call.

Troubleshooting

"publishes no OAuth authorization server" or "registers no OAuth client named CollHub MCP" — the instance does not accept sign-ins from this server yet. The server still starts, and every tool call answers with that error until it does: ask your CollHub administrator to enable OAuth and publish the CollHub MCP client.
The browser never opens — the login URL is on stderr; find it in the host's log for this MCP server. On a headless machine, forward the port as described above.
The server exits at once with "COLLHUB_URL or COLLHUB_INSTANCES is required" — the host did not pass the instance URL; check the env of the registration (or the extension's settings in Claude Desktop).
npx complains about the Node version — the server needs Node 22.19 or later; npx runs whatever node is first on your PATH.
Signed in as the wrong user — ask the assistant to login with switch user, or delete the session file under ~/.config/collhub-mcp/sessions/.

About

@collhub/mcp is part of CollHub and is released under the MIT license. Its source is not published as an open-source project; questions and requests go through your CollHub contact.