# Connect an agent (MCP)

BigHugger runs a hosted MCP server, so a coding agent can search the index, ask research questions
and build workbooks as ordinary tool calls. The server runs on our side; connecting an agent only
tells it where the server is and gives it a key, and one command does both after you approve it in
your browser.

The server speaks streamable HTTP at one address:

```text
https://api.bighugger.com/mcp
```

## Connect in one command

On the **Connect agent** page, pick your agent and press **Copy for your agent**. That copies a
SKILL.md to paste into the agent: it tells the agent to run the command below, and how to use the
tools once they are connected. You can also run the command yourself. It needs Node 20 or newer.

```sh
curl -fsSL https://bighugger.com/connect.mjs | node --input-type=module - --client cursor
```

`--client` takes `claude-code`, `codex`, `cursor` or `opencode`. Leave it off to connect every
supported agent found on the machine. The command prints a link to bighugger.com; open it where you
are signed in and approve. The agent receives a key of its own and the command writes it into that
agent's MCP configuration, so there is nothing to copy and no key passes through a chat or a
clipboard. Restart the agent and the tools appear.

Each connected agent has its own key, listed under *Connected agents*. Revoking one in Settings cuts
off that agent and nothing else.

## Set it up by hand

If you would rather manage the key yourself, create one in Settings and add the server as below.

### Claude Code

```sh
claude mcp add --transport http bighugger https://api.bighugger.com/mcp \
  --header "Authorization: Bearer $BIGHUGGER_KEY"
```

### Cursor, Windsurf and other clients

Most clients read an `.mcp.json` file (Cursor also reads `~/.cursor/mcp.json`). Written by hand, the file
looks like this:

```json
{
  "mcpServers": {
    "bighugger": {
      "type": "http",
      "url": "https://api.bighugger.com/mcp",
      "headers": { "Authorization": "Bearer bh_live_..." }
    }
  }
}
```

A client that only speaks stdio can reach the server through a bridge such as
`npx mcp-remote https://api.bighugger.com/mcp --header "Authorization: Bearer bh_live_..."`.

## Tools

| Tool | What it does | Typical cost |
| --- | --- | --- |
| `search` | Ranked rows from the index, each with its id, link and facts such as licence, size and parameter count. Use it first. | 1 token |
| `ask` | The research agent. It plans and runs searches across the index and the open web, then writes one cited recommendation. It returns a `thread_id`. | about 520 tokens, around 40 s |
| `create_workbook` | Packs an answer as something that runs: a notebook, a pinned environment and the model files. Pass the `thread_id` from `ask`, or pass a question and it runs `ask` first. | 83 tokens on top of the ask |
| `list_workbooks` | Workbooks this account has built, newest first, with download links. | free |
| `balance` | Tokens left, and where to top up. | free |

Every tool draws on the same balance as the HTTP API and keeps the same rules. A key without the
`search` scope cannot use `search` here either, and a call made on an empty balance returns
`out_of_tokens` with a top-up link, which the agent is told to pass on to you.

## Errors

A missing or unknown key returns HTTP `401`, and the `WWW-Authenticate` header says so. The server
only accepts `POST`. A `GET` returns `405`, because there is no event stream to subscribe to and every
call is one request and one response.