> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup

> Install and configure the Hubify MCP server for Claude Code, Cursor, and any MCP host. Read and write lab data directly from your AI coding assistant.

# 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):

```bash theme={null}
npm install -g hubify-labs
```

<Note>
  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.
</Note>

Verify the MCP server is on your PATH:

```bash theme={null}
hubify mcp --help
```

## Configuration

### Claude Code (global — all sessions)

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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`:

```markdown theme={null}
## 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

<AccordionGroup>
  <Accordion title="'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:

    ```json theme={null}
    {
      "mcpServers": {
        "hubify": {
          "command": "/usr/local/bin/hubify",
          "args": ["mcp"],
          "env": { ... }
        }
      }
    }
    ```

    Find the path with `which hubify`.
  </Accordion>

  <Accordion title="No tools showing in Claude Code">
    1. Confirm `~/.claude/mcp.json` is valid JSON: `cat ~/.claude/mcp.json | python3 -m json.tool`
    2. Run `hubify mcp --health` to check the resolution chain
    3. Restart Claude Code — MCP servers are loaded at session start
  </Accordion>

  <Accordion title="CONVEX_URL not resolving">
    Run the health check: `hubify mcp --health`

    If it shows `[HTTP error]` for CONVEX\_URL, the URL is wrong. Find the correct one in **Settings → Developer** in the Hubify web app.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    # 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.
  </Accordion>
</AccordionGroup>