---
title: "Brainfish MCP Server"
description: "The Brainfish MCP (Model Context Protocol) Server connects AI assistants — Cursor, Claude Desktop, Claude.ai, VS Code Copilot, and any other MCP-compatible tool — directly to your Brainfish knowledge base. You can search, read, write, and manage documents and collections without leaving your AI assistant."
canonical_url: "https://help.brainfi.sh/articles/brainfish-mcp-server-4wP3c66Aum"
md_url: "https://help.brainfi.sh/articles/brainfish-mcp-server-4wP3c66Aum.md"
---
# Brainfish MCP Server

The Brainfish MCP (Model Context Protocol) Server connects AI assistants — Cursor, Claude Desktop, [Claude.ai](http://Claude.ai), VS Code Copilot, and any other MCP-compatible tool — directly to your Brainfish knowledge base. You can search, read, write, and manage documents and collections without leaving your AI assistant.

**Hosted endpoint:** `https://mcp.brainfi.sh`


---

## Table of Contents


 1. [Getting Started](#getting-started)
 2. [Credentials](#credentials)
 3. [Authentication](#authentication)
 4. [Setup by Platform](#setup-by-platform)
    * [Claude.ai Web](#claudeai-web)
    * [Cursor](#cursor)
    * [Claude Desktop](#claude-desktop)
    * [VS Code Copilot](#vs-code-copilot)
 5. [Tools Reference](#tools-reference)
    * [Search & Documents](#search--documents)
    * [Suggestions](#suggestions)
    * [Collections](#collections)
    * [AI & Answers](#ai--answers)
    * [Catalogs](#catalogs)
    * [Auth](#auth)
 6. [MCP Resources](#mcp-resources)
 7. [Example Prompts](#example-prompts)
 8. [Error Reference](#error-reference)
 9. [Self-Hosting](#self-hosting)
10. [FAQ](#faq)


---

## Getting Started

The fastest way to connect is via **[Claude.ai](http://Claude.ai)** (fully automated OAuth) or by pasting a config snippet into **Cursor** or **Claude Desktop**.

You need two things before you begin:

| Credential | Required for |
|----|----|
| **API Token** (`bf_api_...`) | All tools |
| **Agent Key** | `brainfish_generate_answer` and `brainfish_generate_follow_ups` only |


---

## Credentials

### API Token


1. Open the [Brainfish Dashboard](https://app.brainfi.sh)
2. Go to **Settings → API Tokens**
3. Click **Create token** and copy the value — it starts with `bf_api_`

### Agent Key


1. Open the [Brainfish Dashboard](https://app.brainfi.sh)
2. Go to **Agents**
3. Click any agent to reveal and copy its key

> The `agent-key` is **only required** for the two AI answer tools. All document, collection, and catalog tools work with the API token alone.


---

## Authentication

The server supports two authentication methods depending on the client.

### OAuth 2.1 — [Claude.ai](http://Claude.ai) (automatic)

[Claude.ai](http://Claude.ai) handles the full OAuth 2.1 + PKCE flow automatically. You enter your API token once in a browser window; Claude stores the resulting access token and reuses it on every call.

The server is fully stateless — credentials are encoded inside the token itself. No database or server-side secrets are involved.

| Endpoint | URL |
|----|----|
| Discovery | `https://mcp.brainfi.sh/.well-known/oauth-authorization-server` |
| Authorization | `https://mcp.brainfi.sh/authorize` |
| Token Exchange | `https://mcp.brainfi.sh/token` |
| Client Registration | `https://mcp.brainfi.sh/register` |

### Bearer Token — Cursor, Claude Desktop, VS Code

Pass your API token directly in the `Authorization` header on every request:

```
Authorization: Bearer bf_api_YOUR_TOKEN

agent-key: YOUR_AGENT_KEY
```

Alternatively you can use `x-brainfish-api-key` or `x-api-key` as the header name — these take priority over `Authorization`.


---

## Setup by Platform

### [Claude.ai](http://Claude.ai) Web


1. Go to **[claude.ai/settings/integrations](https://claude.ai/settings/integrations)**
2. Click **Add custom connector**
3. Fill in:
   * **Name:** `Brainfish`
   * **URL:** `https://mcp.brainfi.sh`
4. Click **Add** — a browser window opens
5. Enter your `bf_api_...` API token (and optionally your Agent Key)
6. Click **Authorize**

Claude stores the token and manages re-authentication automatically.


---

### Cursor

Go to **Settings → Features → MCP Servers → Add new global MCP server** and paste:

```json
{
  "mcpServers": {
    "brainfish": {
      "url": "https://mcp.brainfi.sh",
      "headers": {
        "Authorization": "Bearer bf_api_YOUR_TOKEN",
        "agent-key": "YOUR_AGENT_KEY"
      }
    }
  }
}
```

Replace `bf_api_YOUR_TOKEN` and `YOUR_AGENT_KEY` with your actual credentials.


---

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "brainfish": {
      "url": "https://mcp.brainfi.sh",
      "headers": {
        "Authorization": "Bearer bf_api_YOUR_TOKEN",
        "agent-key": "YOUR_AGENT_KEY"
      }
    }
  }
}
```

Restart Claude Desktop after saving.


---

### VS Code Copilot

Add to your **User Settings (JSON)** (`Cmd+Shift+P` → `Open User Settings JSON`):

```json
{
  "mcp": {
    "servers": {
      "brainfish": {
        "type": "http",
        "url": "https://mcp.brainfi.sh",
        "headers": {
          "Authorization": "Bearer bf_api_YOUR_TOKEN",
          "agent-key": "YOUR_AGENT_KEY"
        }
      }
    }
  }
}
```


---

## Tools Reference

### Search & Documents

#### `brainfish_search_documents`

Semantic search across your Brainfish knowledge base.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `query` | string | ✅ | — | Search query (1–2000 characters) |
| `collectionId` | UUID | — | — | Restrict search to a single collection |
| `collectionIds` | UUID\[\] | — | — | Restrict search to multiple collections |
| `dateFilter` | enum | — | — | `day`, `week`, `month`, or `year` |
| `limit` | number | — | `10` | Results to return (1–25) |
| `cmsOnly` | boolean | — | `false` | Only search CMS-sourced content |

**Example prompt:**

> "Search Brainfish for articles about password reset"


---

#### `brainfish_get_document`

Retrieve a specific document's full content.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `id` | string | ✅ | Document UUID or URL slug |

**Example prompt:**

> "Get the Brainfish document with ID `abc-123`"


---

#### `brainfish_list_documents`

List documents with filtering and pagination.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `collectionId` | UUID | — | — | Filter by collection |
| `sort` | enum | — | `updatedAt` | `createdAt`, `updatedAt`, `publishedAt`, `title` |
| `direction` | enum | — | `DESC` | `ASC` or `DESC` |
| `limit` | number | — | `25` | Results per page (1–100) |
| `offset` | number | — | `0` | Pagination offset |

**Example prompt:**

> "List all documents in my Help Center collection, sorted by title"


---

#### `brainfish_create_document`

Create a new document in a collection.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `collectionId` | UUID | ✅ | — | Collection to create the document in |
| `title` | string | — | `""` | Document title |
| `text` | string | — | `""` | Document content in Markdown |
| `parentDocumentId` | UUID | — | — | Create as a child document |
| `publish` | boolean | — | `false` | Publish immediately |
| `template` | boolean | — | `false` | Mark as a template |
| `templateId` | UUID | — | — | Base on an existing template |

**Example prompt:**

> "Create a new published document titled 'Webhook Setup Guide' in the Help Center collection"


---

#### `brainfish_update_document`

Update an existing document's title, content, or settings.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `id` | string | ✅ | Document UUID or URL slug |
| `title` | string | — | New title |
| `text` | string | — | New content in Markdown |
| `publish` | boolean | — | Publish or unpublish |
| `fullWidth` | boolean | — | Enable full-width display |
| `collectionId` | UUID | — | Move to a different collection |
| `siteEnabled` | boolean | — | Make publicly visible on site |

**Example prompt:**

> "Update the OAuth guide document to add a section on PKCE and publish it"


---

#### `brainfish_delete_document`

Delete a document. Soft-deletes by default; use `permanent: true` to remove it entirely.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `id` | string | ✅ | — | Document UUID or URL slug |
| `permanent` | boolean | — | `false` | Permanently delete (cannot be undone) |

> **Warning:** `permanent: true` is irreversible.


---

### Suggestions

Suggestions enter a review queue rather than modifying documents directly, making them safe to use with AI assistants.

#### `brainfish_suggest_document_changes`

Propose edits to an existing document.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `documentId` | string | ✅ | — | Target document UUID or slug |
| `text` | string | ✅ | — | Suggested document content in Markdown |
| `title` | string | — | — | Suggested new title |
| `reason` | string | — | `""` | Reason for the change |
| `source` | string | — | `mcp_client` | Source identifier |
| `sourceId` | string | — | — | External reference ID |

**Example prompt:**

> "Suggest updating the API authentication guide with the new token format"


---

#### `brainfish_suggest_new_document`

Suggest creating a brand-new document (routed through the suggestion system).

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `baseDocumentId` | string | ✅ | — | Existing document to anchor the suggestion to |
| `title` | string | ✅ | — | Title for the new document |
| `text` | string | ✅ | — | Content in Markdown |
| `reason` | string | — | Auto-generated | Reason for creating this document |
| `source` | string | — | `mcp_client` | Source identifier |
| `collectionId` | string | — | — | Target collection for the new document |


---

#### `brainfish_update_suggestion`

Edit a pending suggestion before it is reviewed.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `suggestionId` | UUID | ✅ | Suggestion UUID |
| `title` | string | — | Updated title |
| `text` | string | — | Updated content |
| `reason` | string | — | Updated reason |


---

#### `brainfish_generate_article_suggestion`

Trigger the **Brainfish Knowledge Discovery Agent** to analyse content and generate article suggestions asynchronously. Returns a `task_id` you can use to track progress.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `content` | string | ✅ | — | Content to analyse (Markdown) |
| `collection_id` | UUID | — | — | Target collection for new article drafts |
| `new_article` | boolean | — | `false` | `true` = create new drafts; `false` = suggest updates to existing docs |

> **Note:** Results are cached for 5 minutes. A duplicate request within that window returns a `409 conflict`.


---

### Collections

#### `brainfish_list_collections`

List all collections your token can access.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `sortBy` | enum | — | `updatedAt` | `updatedAt`, `index`, or `name` |
| `direction` | enum | — | `DESC` | `ASC` or `DESC` |
| `limit` | number | — | `25` | Results per page (1–100) |
| `offset` | number | — | `0` | Pagination offset |


---

#### `brainfish_get_collection`

Get details of a specific collection.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `id` | string | ✅ | Collection ID |


---

#### `brainfish_create_collection`

Create a new collection to organise documents.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `name` | string | ✅ | Collection name |
| `description` | string | — | Description |
| `icon` | string | — | Emoji or icon name |
| `color` | string | — | Hex colour (e.g. `#FF5733`) |
| `permission` | enum | — | `read` or `read_write` |
| `sharing` | boolean | — | Enable sharing |
| `siteEnabled` | boolean | — | Make publicly visible on site |


---

#### `brainfish_update_collection`

Update an existing collection's properties.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `id` | string | ✅ | Collection ID |
| `name` | string | — | New name |
| `description` | string | — | New description |
| `icon` | string | — | New icon |
| `color` | string | — | New hex colour |
| `permission` | enum | — | `read` or `read_write` |
| `sharing` | boolean | — | Toggle sharing |
| `siteEnabled` | boolean | — | Toggle public visibility |


---

#### `brainfish_delete_collection`

Delete a collection and **all documents within it**.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `id` | string | ✅ | Collection ID |

> **Warning:** This is irreversible. You cannot delete the last collection in a team.


---

### AI & Answers

These two tools require the `agent-key` header in addition to your API token.

#### `brainfish_generate_answer`

Generate a streaming AI answer sourced from your knowledge base.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `query` | string | ✅ | Question to answer (1–2000 characters) |
| `conversationId` | string | — | Continue an existing conversation (25-char ID) |

**Example prompt:**

> "Use Brainfish to answer: what is the rate limit for the API?"


---

#### `brainfish_generate_follow_ups`

Generate suggested follow-up questions based on a completed AI conversation.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `conversationId` | string | ✅ | — | Conversation ID from a previous `generate_answer` call |
| `limit` | number | — | `3` | Number of follow-ups to return (1–10) |


---

### Catalogs

Catalogs let you sync external content (websites, CMS platforms, Zendesk, Notion, etc.) into Brainfish for search and AI answers.

#### `brainfish_list_catalogs`

List all catalogs for your team.

| Parameter | Type | Required | Default | Description |
|----|----|----|----|----|
| `source` | enum | — | — | Filter by source: `cms`, `website`, `zendesk`, `github`, `notion`, `confluence`, `intercom`, `freshdesk`, `helpscout`, `readme`, `readmev2`, `oas`, `helpjuice`, `googledrive`, `guru`, `discovery`, `external` |
| `status` | enum | — | — | Filter by sync status: `inprogress`, `completed`, `failed` |
| `limit` | number | — | `25` | Results per page (1–100) |
| `offset` | number | — | `0` | Pagination offset |


---

#### `brainfish_get_catalog`

Get a catalog by ID, including its content count.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `id` | UUID | ✅ | Catalog UUID |


---

#### `brainfish_create_catalog`

Create a new catalog. After creation, use `brainfish_sync_catalog_content` to push content into it.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `name` | string | ✅ | Catalog name (max 255 chars) |
| `source` | enum | ✅ | Source type (same enum as `list_catalogs`) |
| `slug` | string | — | Unique slug (max 100 chars) |
| `configurations` | object | — | Source-specific configuration options |


---

#### `brainfish_sync_catalog_content`

Full-sync an array of content files to a catalog. Files not included in the request are **removed** from the catalog.

| Parameter | Type | Required | Description |
|----|----|----|----|
| `id` | UUID | ✅ | Catalog UUID |
| `files` | array | ✅ | Array of content file objects (see below) |

Each item in `files`:

| Field | Type | Required | Description |
|----|----|----|----|
| `url` | string | ✅ | Unique identifier / URL for this file within the catalog |
| `content` | string | ✅ | File content (Markdown or plain text) |
| `title` | string | ✅ | Content title |

> **Note:** This is a full replace. Any file present in the catalog but absent from this request will be deleted.


---

### Auth

#### `brainfish_validate_token`

Validate your API token and retrieve the associated user and team information.

No parameters required.

**Example prompt:**

> "Validate my Brainfish token and show me my account info"


---

## MCP Resources

Resources expose read-only content via `brainfish://` URIs. MCP-compatible clients can reference them directly.

| URI | MIME Type | Description |
|----|----|----|
| `brainfish://collections` | `application/json` | All accessible collections |
| `brainfish://collection/{id}` | `application/json` | Collection details and metadata |
| `brainfish://collection/{id}/documents` | `application/json` | Documents within a collection |
| `brainfish://document/{id}` | `text/markdown` | Full document content |
| `brainfish://search?query={q}` | `application/json` | Semantic search results |


---

## Example Prompts

### Search & Read

```
"Use Brainfish to answer: how do I reset my password?"
```

```
"Search Brainfish for our API authentication guide"
```

```
"List all collections in my Brainfish workspace"
```

```
"Show me the documents in the Help Center collection"
```

### Create & Update Content

```
"Create a new document in the Help Center collection about webhook setup"
```

```
"Update the OAuth guide to add a section on refresh tokens and publish it"
```

```
"Search Brainfish for our API authentication guide and update it with the new OAuth steps"
```

### Suggestions (safe for AI assistants)

```
"Suggest improvements to the onboarding document based on these support tickets"
```

```
"Generate article suggestions from this conversation transcript and add them to the Help Center collection"
```

### Catalogs

```
"Sync these 5 markdown files to my CMS catalog"
```

```
"Show me which catalogs have failed their last sync"
```


---

## Error Reference

| HTTP Code | Error Code | Meaning | What to do |
|----|----|----|----|
| `401` | `authentication_required` | Missing or invalid API token | Check your `Authorization` header value |
| `403` | `forbidden` | Token lacks permission for this resource | Verify the token has the right workspace access |
| `404` | `not_found` | Document, collection, or catalog does not exist | Check the ID/slug is correct |
| `409` | `conflict` | Duplicate request (article suggestions are cached for 5 min) | Wait 5 minutes before re-submitting |
| `422` | `validation_failed` | Invalid request parameters | Check required fields and value formats |
| `429` | `rate_limit_exceeded` | 25 requests/min limit reached | Back off and retry after a short wait |
| `500` | `internal_error` | Brainfish server error | Retry; contact support with the `requestId` |

Every error response includes a `requestId` field. Share it with Brainfish support for faster debugging.


---

## Self-Hosting

The server is a standard Next.js application you can deploy to Vercel with a single click — no environment variables required.

 ![Deploy with Vercel](https://vercel.com/button " =103x32")

Optional environment variables:

| Variable | Default | Purpose |
|----|----|----|
| `BRAINFISH_API_URL` | `https://api.brainfi.sh` | Override the upstream Brainfish API base URL |
| `BRAINFISH_TIMEOUT` | `30000` | HTTP timeout in milliseconds |
| `BRAINFISH_RETRY_ATTEMPTS` | `3` | Retry count on `429` / `5xx` responses |
| `BRAINFISH_RETRY_DELAY` | `1000` | Base retry delay in milliseconds (exponential backoff applied) |


---

## FAQ

**Do I need an** `agent-key` for all tools? No. The agent key is only required for `brainfish_generate_answer` and `brainfish_generate_follow_ups`. All document, collection, catalog, and suggestion tools work with just the API token.

**Is my API token stored on the server?** No. The server is fully stateless. Your credentials are encoded within the OAuth access token itself and are never persisted server-side.

**What happens if I call** `brainfish_sync_catalog_content` with a partial file list? Files present in the catalog but absent from the request are permanently removed. Always include the complete set of files you want to keep.

**Can I use a URL slug instead of a UUID for documents?** Yes. The `brainfish_get_document`, `brainfish_update_document`, and `brainfish_delete_document` tools accept either a UUID or a URL slug in the `id` parameter.

**What Markdown flavour should I use for document content?** Standard CommonMark Markdown is supported for the `text` field in create/update operations.

**Where do I find the** `conversationId` for follow-up questions? It is returned in the response from `brainfish_generate_answer`. Pass it to `brainfish_generate_follow_ups` to get related questions.


---

## Support

* **Help Center:** [help.brainfi.sh](https://help.brainfi.sh)
* **API Reference:** [help.brainfi.sh/articles/api-reference-7mjzVCAmeM](https://help.brainfi.sh/articles/api-reference-7mjzVCAmeM)
* **GitHub Issues:** [github.com/brainfish-ai/brainfish-mcp-server/issues](https://github.com/brainfish-ai/brainfish-mcp-server/issues)
* **Dashboard:** [app.brainfi.sh](https://app.brainfi.sh)