Brainfish MCP Server

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.

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

---

Table of Contents

1. Getting Started
2. Credentials
3. Authentication
4. Setup by Platform
   • Claude.ai Web
   • Cursor
   • Claude Desktop
   • VS Code Copilot
5. Tools Reference
   • Search & Documents
   • Suggestions
   • Collections
   • AI & Answers
   • Catalogs
   • Auth
6. MCP Resources
7. Example Prompts
8. Error Reference
9. Self-Hosting
10. FAQ

---

Getting Started

The fastest way to connect is via 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
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
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 (automatic)

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 Web

1. Go to 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:

{
  "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):

{
  "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):

{
  "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.

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
• API Reference: help.brainfi.sh/articles/api-reference-7mjzVCAmeM
• GitHub Issues: github.com/brainfish-ai/brainfish-mcp-server/issues
• Dashboard: app.brainfi.sh