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
• Preferred MCP endpoint: https://api.agent-brains.com/mcp
• Legacy SSE endpoint: https://api.agent-brains.com/sse
• Purpose: expose tenant-aware Knowledge Base tools over MCP

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

Connect an MCP client

Agent Brains exposes a standard Streamable HTTP MCP endpoint:

https://api.agent-brains.com/mcp

Send an Agent Brains API key as either Authorization: Bearer <your-api-key> or x-api-key: <your-api-key>.

Option 1: Direct Streamable HTTP (preferred)

If your MCP client supports remote MCP servers over Streamable HTTP and can send an authorization header, connect it directly to:

https://api.agent-brains.com/mcp

This is the standard integration path. Use the client's own remote-MCP configuration UI or documentation to set the endpoint and bearer token.

Option 2: Use mcp-remote for stdio-only clients

Some MCP clients only support servers launched as local stdio processes. In that case, use the open-source mcp-remote bridge. It runs locally and forwards MCP traffic to the Agent Brains HTTP endpoint. mcp-remote is a third-party compatibility bridge, not an Agent Brains package, SDK, or service.

Example configuration:

{
  "mcpServers": {
    "agent-brains": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.agent-brains.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AGENT_BRAINS_AUTHORIZATION}"
      ],
      "env": {
        "AGENT_BRAINS_AUTHORIZATION": "Bearer <your-api-key>"
      }
    }
  }
}

The header value intentionally comes from an environment variable. Do not put a real API key in a committed configuration file. The no-space Authorization:${AGENT_BRAINS_AUTHORIZATION} syntax also avoids argument-parsing issues in some desktop clients.

Configure either direct HTTP or mcp-remote for a client, not both. Both paths expose the same Agent Brains MCP tools.

Option 3: Use @agent-brains/mcp-client

Agent Brains also publishes @agent-brains/mcp-client, a local stdio proxy package for clients that launch MCP servers as commands. Use version 1.3.0 or newer.

Example configuration:

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

Configure only one Agent Brains MCP connection path for a client: direct HTTP, mcp-remote, or @agent-brains/mcp-client.

Legacy SSE compatibility

Use https://api.agent-brains.com/sse only when a client or network requires the legacy SSE transport. With mcp-remote, use --transport sse-only for that endpoint. Prefer /mcp with http-only for new configurations.

Authentication

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

Supported headers:

• Authorization: Bearer <your-api-key>
• x-api-key: <your-api-key>

The gateway resolves the authenticated workspace from the API key and enforces the knowledge-base scope for Knowledge Base tools.

Available Tools

Health

health_check

Simple availability check for the public gateway.

Parameters: none

Knowledge Base read tools

There is no dedicated MCP tool to retrieve one attachment or list attachments. Use the HTTP API for attachment reads.

Knowledge Base write tools

delete-entity and delete-category are destructive actions. Deletions are permanent and cannot be undone.

For MCP, attachment creation accepts JSON/base64 content only. Use the HTTP multipart endpoint for large local files. Attachment updates can change metadata, type, or entity links.

Write tool parameters

Use the released MCP schema for the full parameter tables. Current tool contracts require:

Conversation tools

Use Conversation tools when an agent needs to inspect or continue customer conversations handled by AgentBrains. The authenticated workspace is resolved from the API key.

Conversation channels supported by the public gateway are web-chat and email. Numeric filters such as source, status, and type should be passed as numbers.

Document Structuring tools

Use Document Structuring tools to start asynchronous document processing and check task status or result later. The authenticated workspace is resolved from the API key.

create-structuring-task returns a taskId; it does not wait for processing to finish. Call get-structuring-task later to retrieve status, progress, and result. If categoryId is omitted, AgentBrains processes the document through the general category flow.

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-categories to browse taxonomy before deep retrieval.
• Use get-entity when you already know the entity ID.
• Use write tools only when the user explicitly asks to create, update, or delete Knowledge Base data.
• Confirm destructive entity or category deletion before calling delete-entity or delete-category.
• 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, retrieve, and manage Knowledge Base information accurately and efficiently.

Rules:
- Use MCP tools instead of inventing data.
- Before semantic search, 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 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-categories` or `get-knowledge-base-snapshot`.
- When the user asks for a specific known entity, call `get-entity` with its ID.
- Do not guess missing required parameters. Ask a clarification question when needed.
- Use write tools only after the user clearly requests a Knowledge Base change.
- Confirm permanent entity or category deletion before using `delete-entity` or `delete-category`.
- 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-categories without a category ID
2. If needed, call it again with a selected category ID

Create a Knowledge Base entity

1. Collect the required name and category
2. Add any available content, source, SKU, tags, attachments, relations, or status
3. Call create-entity
4. Summarize the created entity returned by the tool

Security and troubleshooting

• API keys are secrets. Never place a real key in shared documentation, source control, screenshots, or issue reports.
• A 401 response normally means the key is missing, malformed, expired, for the wrong environment, or invalid.
• A 400 response normally means the request parameters are invalid.
• A 404 response means the requested resource is not available in the authenticated tenant.
• Restart the MCP host after changing its local configuration.
• Use only the documented public MCP endpoints for customer connection setup.