# MCP servers

> Add MCP servers to BountyHub agents, choose a transport, and authenticate with None, an API key, or a platform-managed connection.

## Add a server

Open your agent space at `/u/<you>/bh-agent/mcp-servers` and choose **Add
custom MCP**. Give the server a name, then configure at least one transport:

<table>
<thead>
  <tr>
    <th>
      Transport
    </th>
    
    <th>
      Use it for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Command
      </strong>
    </td>
    
    <td>
      A local MCP server the runner starts over stdio, such as <code>
        npx -y @modelcontextprotocol/server-memory
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Streamable HTTP
      </strong>
    </td>
    
    <td>
      A remote MCP endpoint such as <code>
        https://mcp.example.com/mcp
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

SSE is not supported yet. Use Command or Streamable HTTP.

After saving, enable the server for a project on the project's **Agent → MCP
servers** tab. Enabling it makes it available; it does not grant it to every
step automatically.

## Authentication

### None

Use this for local servers that need no credentials, or for a trusted
internal endpoint.

### API key

An API key is stored with the MCP server entry and passed to the runner only
for that agent task.

- **Streamable HTTP** sends it as `Authorization: Bearer <key>`.
- **Command** exposes it to the child process as the `MCP_API_KEY`
environment variable. The server must read that variable.

The key is not written into workflow source, session logs, or traces. Do not
put credentials in the command or URL instead.

### OAuth

OAuth connections are not supported yet. The UI disables the option and the
runner skips OAuth-configured servers instead of connecting without auth.
Use None or an API key for now.

## Grant it to a workflow step

Reference the server by name in `step.agent`:

```bhw
step.agent(
    prompt = "Review the findings in findings.txt.",
    provider = provider.key("anthropic/personal"),
    tools = [tool.shell(), mcp.server("my-mcp-server")],
    output = agent.output(path = path.file("agent-output.txt")),
)
```

`mcp.server("name")` grants the server; it does not embed its URL or
credentials in the workflow.

## The platform BountyHub server

New projects get the platform-managed **BountyHub** MCP server enabled by
default. You do not install or authenticate it: the runner passes it a
short-lived, task-scoped token. It exposes BountyHub context such as projects,
datasets, workflows, runs, templates, and agent skills.

## Run the BountyHub MCP server yourself

To connect Claude, Cursor, or another MCP client to BountyHub outside the
platform, use the published `bh-mcp` image. Pin the image to the version from
the `bh-mcp-vX.Y.Z` release (the image tag is `vX.Y.Z`).

Create a personal access token with the scopes your tools need (typically
**Projects**, **Project Runs**, **Workflow**, **Workflow Templates**, and
**Workflow Modules**; add **Datasets** for dataset tools). Then point your MCP
client at the container:

```json
{
  "mcpServers": {
    "bountyhub": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BOUNTYHUB_TOKEN",
        "-e",
        "BOUNTYHUB_MCP_HUB_URL=https://bountyhub.org",
        "ghcr.io/bountyhub-org/bh-mcp:vX.Y.Z"
      ]
    }
  }
}
```

The image starts `serve --transport stdio` by default and reads
`BOUNTYHUB_TOKEN` from the environment. Keep the token out of committed files.

To build from source instead:

```bash
cd bountyhub-rs
cargo build -p bh-mcp
```

Then use `/absolute/path/to/bountyhub-rs/target/debug/bh-mcp` as the command
with `["serve", "--transport", "stdio"]`.

`bh-mcp` also has `list-tools` and `call-tool` subcommands for checking an
external MCP server from the terminal.