Model Context Protocol (MCP)

Overview

This project exposes an MCP server for AI agents and LLM clients through the Public Gateway.

• Server URL: https://api.agent-brains.com
• Purpose: expose safe, tenant-aware knowledge base tools over MCP
• Transports protected by middleware: /mcp, /sse, /messages
• Current MCP scope: health check and knowledge base search/browsing tools

The MCP layer is implemented with NestJS resolvers and forwards requests to underlying services, mainly SDS for knowledge base operations.

MCP Client Package

We publish an official npm package — @agent-brains/mcp-client — that acts as a local stdio proxy between any standard MCP client and the Agent Brains Gateway.

Instead of configuring HTTP transports manually, you can run the proxy with npx and let your IDE or chat client communicate over the standard MCP stdio protocol.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "agent-brains": {
      "command": "npx",
      "args": ["-y", "@agent-brains/mcp-client"],
      "env": {
        "AGENT_BRAINS_API_KEY": "<your-api-key>"
      }
    }
  }
}

Cursor

Add the following to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "agent-brains": {
      "command": "npx",
      "args": ["-y", "@agent-brains/mcp-client"],
      "env": {
        "AGENT_BRAINS_API_KEY": "<your-api-key>"
      }
    }
  }
}

Other MCP Clients

Any MCP client that supports the stdio transport can use the same pattern. Point the client's command to npx with the arguments shown above and set the AGENT_BRAINS_API_KEY environment variable.

Authentication

MCP requests require a valid API key unless the request is already associated with an existing MCP session.

Supported headers:

• x-api-key: <key>
• authorization: Bearer <key>

The gateway resolves the tenant from the API key and enforces the knowledge-base scope for the knowledge base tools.

Available Tools

health_check

Simple availability check for the public gateway.

Parameters: none

search-knowledge-base

Semantic search across a selected knowledge base index.

Parameters:

• index (string, required): knowledge base index name
• query (string, required): natural language query
• topK (number, optional, default 10, max 50): number of matches to return
• metadata (object, optional): metadata filters forwarded to SDS

Behavior:

• Maps index to SDS namespace
• Sends a POST request to /retrieve

list-knowledge-base-indexes

Lists available knowledge base indexes.

Parameters:

• status (initial | vectorised | fail, optional): filter by index status
• categoryId (string, optional): filter by category ID
• name (string, optional): text search in index name
• notes (string, optional): text search in index notes

Behavior:

• Sends a GET request to /indexes

search-images

Semantic search over the image index.

Parameters:

• query (string, required): natural language query
• topK (number, optional, default 10, max 50): number of matches to return
• metadata (object, optional): metadata filters forwarded to SDS

Behavior:

• Hardcodes SDS namespace to images
• Sends a POST request to /retrieve

get-entity

Fetches a full knowledge base entity by ID or exact name.

Parameters:

• id (string, optional): entity ID
• name (string, optional): exact entity name

Rules:

• At least one of id or name must be provided

Behavior:

• Sends a GET request to /entities/:key

get-knowledge-base-structure

Browses the category tree for the knowledge base.

Parameters:

• categoryId (string, optional): category to drill into

Behavior:

• Without categoryId, sends GET /categories
• With categoryId, sends GET /categories/:categoryId

Usage Notes For AI Agents

• Prefer search-knowledge-base for text and semantic discovery.
• Prefer search-images only for image-oriented retrieval use cases.
• Use list-knowledge-base-indexes first when the correct index is unknown.
• Use get-knowledge-base-structure to browse taxonomy before deep retrieval.
• Use get-entity when you already know the entity ID or exact name.
• If a tool returns a validation error, fix the parameters and retry instead of guessing new fields.

Recommended Prompt

Use the following prompt when connecting an AI agent to this MCP server:

You are connected to the Agent Brains Public Gateway MCP server.

Your job is to help the user find and retrieve knowledge base information accurately and efficiently.

Rules:
- Use MCP tools instead of inventing data.
- Before searching, identify the most appropriate knowledge base index.
- If the correct index is unknown, call `list-knowledge-base-indexes` first.
- For general semantic search, call `search-knowledge-base` with:
  - `index`: the chosen index name
  - `query`: the user's request rewritten as a focused search query
- For image-related retrieval, call `search-images`. Do not ask the user for an image namespace because it is fixed internally.
- When the user asks to browse categories or structure, call `get-knowledge-base-structure`.
- When the user asks for a specific known entity, call `get-entity` with `id` or exact `name`.
- Do not guess missing required parameters. Ask a clarification question when needed.
- Summarize tool results clearly, and distinguish facts returned by tools from your own reasoning.
- If a tool returns no results, say so plainly and propose the next best query or tool.

Response style:
- Be concise and factual.
- Prefer actionable answers.
- Mention which index you used when performing knowledge base search.

Example Workflows

Find the right index

1. Call list-knowledge-base-indexes
2. Select the best matching index
3. Call search-knowledge-base

Search for product images

1. Call search-images with the user's image-related query
2. Summarize the returned matches

Inspect the taxonomy

1. Call get-knowledge-base-structure without categoryId
2. If needed, call it again with a selected category ID