Skip to content

brainfish-ai/brainfish-mcp-server

BranchesTags

Repository files navigation

Brainfish MCP Server

A Model Context Protocol (MCP) server for Brainfish — giving AI assistants in Cursor, Claude, VS Code, and other MCP-compatible tools direct access to your Brainfish knowledge base.

Endpoint: https://mcp.brainfi.sh

Quick Start

Claude.ai Web (OAuth 2.1 — recommended)

Go to claude.ai/settings/integrations → Add custom connector:

  1. Name: Brainfish
  2. URL: https://mcp.brainfi.sh
  3. Click Add → a browser window opens → enter your Brainfish API token → Authorize

Claude handles the full OAuth flow. No manual token pasting required.

Cursor

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

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

VS Code Copilot

Add to your 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"
        }
      }
    }
  }
}

Getting Your Credentials

Credential Where to find it
bf_api_YOUR_TOKEN Brainfish Dashboard → Settings → API Tokens
YOUR_AGENT_KEY Brainfish Dashboard → Agents → click any agent to copy its key

agent-key is only required for AI answer tools (brainfish_generate_answer, brainfish_generate_follow_ups). All other tools work with the API token alone.

Authentication

The server supports two authentication methods:

OAuth 2.1 (Claude.ai web, automatic)

The server implements the full MCP OAuth 2.1 spec:

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

When Claude.ai calls the MCP server without credentials it receives a 401 with a WWW-Authenticate header pointing to the discovery document. Claude then opens the /authorize page in a browser where you enter your Brainfish API token once. The server issues a Bearer token that Claude stores and re-uses.

No database or server-side secrets are involved. Credentials are encoded inside the tokens themselves (stateless, PKCE-verified).

Bearer Token (Cursor, Claude Desktop, VS Code)

Pass your API token directly in the Authorization header:

Authorization: Bearer bf_api_YOUR_TOKEN

Available Tools (26)

Search & Documents

Tool Description
brainfish_search_documents Semantic search across your knowledge base
brainfish_get_document Get full document content by ID or URL slug
brainfish_list_documents List documents with filtering and pagination
brainfish_create_document Create a new document in a collection
brainfish_update_document Update title, content, or publish status
brainfish_delete_document Soft-delete (or permanently delete) a document

Suggestions

Tool Description
brainfish_suggest_document_changes Propose edits to an existing document (goes through review)
brainfish_suggest_new_document Suggest a new document for creation
brainfish_update_suggestion Update a pending suggestion before review
brainfish_generate_article_suggestion Trigger AI-powered article suggestions from content (async)

Collections

Tool Description
brainfish_list_collections List all accessible collections
brainfish_get_collection Get collection details by ID
brainfish_create_collection Create a new collection
brainfish_update_collection Update collection name, description, visibility
brainfish_delete_collection Delete a collection and all its documents

AI & Answers

Tool Description
brainfish_generate_answer Generate an AI answer from your knowledge base (requires agent-key)
brainfish_generate_follow_ups Generate follow-up questions for a conversation (requires agent-key)

Catalogs

Tool Description
brainfish_list_catalogs List all catalogs with optional filtering
brainfish_get_catalog Get catalog details and content count
brainfish_create_catalog Create a new catalog
brainfish_sync_catalog_content Full sync of content files to a catalog

Sessions & Analytics

Tool Description
brainfish_search_sessions Search chat sessions by query text and filters
brainfish_get_session Get full conversation detail (queries, answers, feedback, analytics)
brainfish_get_session_timeline Get chronological event timeline for a conversation
brainfish_generate_session_insights Generate structured LLM diagnosis of a session

Auth

Tool Description
brainfish_validate_token Validate your API token and return user/team info

MCP Resources (5)

Resources provide read-only, referenceable content via brainfish:// URIs:

URI Description
brainfish://collections All accessible collections
brainfish://collection/{id} Collection details and metadata
brainfish://collection/{id}/documents Documents within a collection
brainfish://document/{id} Full document content in Markdown
brainfish://search?query={q} Semantic search results

Example Prompts

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

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

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

"List all collections in my Brainfish workspace"

"Find recent sessions where users asked about refunds and tell me what went wrong"

"Show me the full conversation for session abc123 and generate insights on why it failed"

Error Handling

HTTP Code Error Meaning
401 authentication_required Missing or invalid API token
403 forbidden Token lacks permission for this resource
404 not_found Resource does not exist
409 conflict Duplicate request (article suggestions cached for 5 min)
422 validation_failed Invalid request parameters
429 rate_limit_exceeded 25 req/min limit reached
500 internal_error Brainfish server error

Responses include a requestId you can share with Brainfish support for debugging.

Local Development

To test your local changes against Claude Desktop:

1. Start the dev server

npm run dev

The server runs at http://localhost:3000 by default (Next.js will use the next available port if 3000 is taken — check the terminal output).

2. Configure Claude Desktop

Claude Desktop does not support URL-based MCP servers — you need mcp-remote as a stdio bridge.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "brainfish-local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/api/mcp",
        "--header",
        "Authorization:Bearer bf_api_YOUR_TOKEN",
        "--header",
        "agent-key:YOUR_AGENT_KEY"
      ]
    }
  }
}

npx will install mcp-remote automatically on first run.

3. Restart Claude Desktop

Claude Desktop requires a full quit and reopen to pick up config changes.

Self-Hosting

The server is a Next.js app deployable to Vercel with zero configuration:

Deploy with Vercel

No environment variables required — credentials are passed per-request.

Support

License

MIT — see LICENSE

About

MCP server for Brainfish knowledge base management. Features include document search, creation, suggestions workflow, collection management, and AI-powered content generation.

brainfish-mcp-server.vercel.app

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages