MCP Setup

The Hubify MCP server gives Claude Code (and any MCP-compatible AI) direct access to your lab — read experiments, create tasks, log events, update papers, and more. All 48 tools work without a browser login for read and write operations.

Prerequisites

Install the Hubify CLI (which includes the MCP server):

npm install -g hubify-labs

The hubify mcp subcommand requires hubify-labs 2.0.0 or later. Run hubify --version to confirm your installed version. If you see 1.x, run npm install -g hubify-labs again to upgrade.

Verify the MCP server is on your PATH:

hubify mcp --help

Configuration

Claude Code (global — all sessions)

Add to ~/.claude/mcp.json (create if it doesn’t exist):

{
  "mcpServers": {
    "hubify": {
      "command": "hubify",
      "args": ["mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud",
        "HUBIFY_LAB_SLUG": "your-lab-slug"
      }
    }
  }
}

Find your CONVEX_URL in the Hubify web app under Settings → Developer. Your lab slug is in the URL when viewing your lab (hubify.com/app/labs/your-lab-slug).

Claude Code (project-level)

To scope the MCP to a specific project directory, add .mcp.json at the project root:

{
  "mcpServers": {
    "hubify": {
      "command": "hubify",
      "args": ["mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud",
        "HUBIFY_LAB_SLUG": "your-lab-slug"
      }
    }
  }
}

Claude Code loads project-level .mcp.json automatically when you open that directory.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "hubify": {
      "command": "hubify",
      "args": ["mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud",
        "HUBIFY_LAB_SLUG": "your-lab-slug"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
`CONVEX_URL`	Yes	Your Convex deployment URL (from Settings → Developer)
`HUBIFY_LAB_SLUG`	No*	Default lab slug — e.g. `bigbounce`, `pta-gw`
`HUBIFY_LAB_ID`	No*	Convex document ID (alternative to slug)
`HUBIFY_API_KEY`	No	API key for write operations (optional — anonymous writes work for most tools)

* Either HUBIFY_LAB_SLUG or HUBIFY_LAB_ID is required to target a specific lab. Without one, the server falls back to the first lab on the deployment.

Verifying Setup

Run the health check before using the MCP in a session:

hubify mcp --health

Expected output:

hubify mcp resolution chain:

  1. --path flag                        –  [skipped]
  2. HUBIFY_MCP_PATH env                –  [skipped]
  3. npm package require.resolve        ✔  [hit]  /usr/local/lib/node_modules/hubify-labs/mcp-server/dist/index.js

  Resolved via node-resolution:
  /usr/local/lib/node_modules/hubify-labs/mcp-server/dist/index.js

env audit:

  CONVEX_URL           ✔  https://your-deployment.convex.cloud [HTTP 200, 193ms]
  HUBIFY_LAB_SLUG      ✔  your-lab-slug → abc123 [labs:getBySlug, 210ms]
  HUBIFY_API_KEY       –  not set — informational only, server runs anonymous Convex queries

  env audit clean — captain setup ready for MCP tool calls.

Switching Labs Mid-Session

You don’t need to restart Claude Code to switch labs. Use the lab_switch tool:

Ask: "Switch to my pta-gw lab"
→ Claude calls: lab_switch({ slug: "pta-gw" })

The switch persists for the rest of that session. The next session resets to the env-configured default.

Testing Your Setup

Once configured, open a new Claude Code session and run through these scenarios to confirm everything works.

Scenario 1: Read lab state

Ask Claude Code:

“Load my Hubify lab context and give me a summary of what’s going on”

Claude should call hubify_get_context_pack and return a snapshot showing your experiments, papers, and recent events. No auth needed.

Scenario 2: Create a task

Ask Claude Code:

“Create a task to run novelty scoring on all papers, priority high”

Claude should call task_create and return a task ID. Open the web app → your lab → Tasks to confirm it appeared.

Scenario 3: Log a research event

Ask Claude Code:

“Log an event that we just finished reviewing the anomaly catalog paper”

Claude should call hubify_log_event with type paper.reviewed. Open the web app → Activity to see it in the feed.

Scenario 4: Search memory

Ask Claude Code:

“What does the lab know about NANOGrav?”

Claude should call memory_search and knowledge_search, then summarize what the lab has stored about that topic.

Scenario 5: Session summary at wrap-up

At the end of a work session, ask:

“Save a summary of what we did today to the lab”

Claude should call hubify_create_session_summary. This persists to the agentEvents ledger so future sessions can see what ran.

Adding MCP Context to Your Project CLAUDE.md

For projects where you always want Claude to use Hubify tools, add this to the project’s CLAUDE.md:

## Hubify Labs

The Hubify MCP server is configured. When working on research tasks, use the
MCP tools to read and write lab state — do not guess, call the tool.

Key tools to use proactively:
- `hubify_get_context_pack` — load lab state at session start
- `hubify_log_event` — log any meaningful state change
- `task_create` — create follow-up tasks from research findings
- `hubify_create_session_summary` — save session summary at wrap-up

Troubleshooting

'hubify: command not found' when MCP server starts

The hubify binary isn’t in the PATH that Claude Code’s MCP launcher uses.Fix: Use the absolute path in your mcp.json:

{
  "mcpServers": {
    "hubify": {
      "command": "/usr/local/bin/hubify",
      "args": ["mcp"],
      "env": { ... }
    }
  }
}

Find the path with which hubify.

No tools showing in Claude Code

Confirm ~/.claude/mcp.json is valid JSON: cat ~/.claude/mcp.json | python3 -m json.tool
Run hubify mcp --health to check the resolution chain
Restart Claude Code — MCP servers are loaded at session start

CONVEX_URL not resolving

Run the health check: hubify mcp --healthIf it shows [HTTP error] for CONVEX_URL, the URL is wrong. Find the correct one in Settings → Developer in the Hubify web app.

lab_switch doesn't persist between sessions

This is expected — lab_switch is session-scoped. To change the default lab permanently, update HUBIFY_LAB_SLUG in your ~/.claude/mcp.json.

Write tools return errors

Most write tools work without authentication (anonymous Convex writes). If you see errors on task_create, memory_save, etc., run the smoke test:

# Replace with your actual CONVEX_URL and lab ID
curl -s -X POST "https://your-deployment.convex.cloud/api/mutation" \
  -H "Content-Type: application/json" \
  -d '{"path":"functions/tasks:create","args":{"labId":"YOUR_LAB_ID","title":"test","status":"todo","priority":"low"},"format":"json"}'

A {"status":"success","value":"..."} response confirms writes work. Find your lab ID in Settings → Developer.

Documentation Index

​MCP Setup

​Prerequisites

​Configuration

​Claude Code (global — all sessions)

​Claude Code (project-level)

​Cursor

​Environment Variables

​Verifying Setup

​Switching Labs Mid-Session

​Testing Your Setup

​Scenario 1: Read lab state

​Scenario 2: Create a task

​Scenario 3: Log a research event

​Scenario 4: Search memory

​Scenario 5: Session summary at wrap-up

​Adding MCP Context to Your Project CLAUDE.md

​Troubleshooting

MCP Setup

Prerequisites

Configuration

Claude Code (global — all sessions)

Claude Code (project-level)

Cursor

Environment Variables

Verifying Setup

Switching Labs Mid-Session

Testing Your Setup

Scenario 1: Read lab state

Scenario 2: Create a task

Scenario 3: Log a research event

Scenario 4: Search memory

Scenario 5: Session summary at wrap-up

Adding MCP Context to Your Project CLAUDE.md

Troubleshooting