Connect your agents to Brainfish with A2A and MCP

Brainfish supports enterprise agent integrations using Agent2Agent (A2A) and Model Context Protocol (MCP).

These integrations allow your own AI agents, workflow assistants, or orchestration systems to securely connect with Brainfish agents and approved Brainfish knowledge tools.

A2A and MCP access is available by request. Contact your Brainfish account team to enable it for your workspace.

What You Can Build

With A2A and MCP access, your agents can connect to Brainfish to:

• Discover available Brainfish agents and their capabilities.
• Ask Brainfish agents product, support, onboarding, policy, or workflow questions.
• Receive governed answers with citations.
• Request clarification when a question is ambiguous.
• Search approved Brainfish knowledge through MCP.
• Use Brainfish cited question answering through MCP.
• Track request status, errors, and usage through audited integration activity.

Brainfish remains responsible for knowledge retrieval, answer generation, citations, and access control. Your agents do not need direct access to Brainfish internals.

A2A vs MCP

Brainfish supports two integration patterns.

Protocol	Use it when	Example
A2A	You want your agent to collaborate with a Brainfish agent	Your workflow agent asks Brainfish, "What should we tell this customer?"
MCP	You want an approved agent to call a specific Brainfish tool	Your internal agent calls brainfish.search_knowledge before drafting a response

Most customers start with A2A, then add MCP tools if they need lower-level access to approved Brainfish capabilities.

Available Endpoints

All customer integrations use the Brainfish API domain:

https://api.brainfi.sh

Your exact tenant and agent slugs are provided after access is approved.

Example A2A base URL:

https://api.brainfi.sh/a2a/{tenantSlug}/{agentSlug}

Example MCP base URL:

https://api.brainfi.sh/mcp/{tenantSlug}

A2A Access

A2A allows your agent to discover and collaborate with a Brainfish agent.

After access is enabled, Brainfish provides an Agent Card endpoint:

GET https://api.brainfi.sh/a2a/{tenantSlug}/{agentSlug}/.well-known/agent-card.json

The Agent Card describes:

• The Brainfish agent name and description.
• Supported capabilities.
• Supported skills.
• Authentication requirements.
• The A2A endpoint URL.

Example Agent Card:

{
  "name": "Brainfish Support Knowledge Agent",
  "description": "Answers support, product, onboarding, policy, and workflow questions using governed Brainfish knowledge.",
  "url": "https://api.brainfi.sh/a2a/company/support",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "citations": true,
    "clarification": true
  },
  "skills": [
    {
      "id": "answer_knowledge_question",
      "name": "Answer knowledge question",
      "description": "Provides a cited answer from approved Brainfish knowledge."
    },
    {
      "id": "suggest_next_step",
      "name": "Suggest next step",
      "description": "Suggests the next support, onboarding, or workflow action."
    }
  ],
  "authentication": {
    "schemes": ["bearer"]
  }
}

Supported A2A Capabilities

The initial A2A integration supports:

• Text-based task submission.
• Task status retrieval.
• Task cancellation.
• Optional streaming with server-sent events.
• Cited final answers.
• Clarification prompts.
• Fallback responses when Brainfish cannot answer from approved knowledge.

Supported task states:

State	Meaning
submitted	The request was accepted
working	Brainfish is retrieving knowledge or generating an answer
input-required	Brainfish needs clarification
completed	The final answer is available
failed	The task failed
canceled	The task was canceled

Example A2A Request

{
  "jsonrpc": "2.0",
  "id": "req_123",
  "method": "tasks.send",
  "params": {
    "skillId": "answer_knowledge_question",
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "What should a customer do if they cannot find their settlement booking?"
        }
      ]
    },
    "metadata": {
      "source": "customer-workflow-agent",
      "region": "au"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": "req_123",
  "result": {
    "taskId": "task_456",
    "status": {
      "state": "completed"
    },
    "artifacts": [
      {
        "name": "answer",
        "parts": [
          {
            "kind": "text",
            "text": "The customer should first confirm they are in the correct workspace and search using the matter reference. If the booking is still not visible, they should check whether the settlement was created under another matter or contact support with the matter reference and settlement date."
          }
        ]
      }
    ],
    "metadata": {
      "citations": [
        {
          "title": "Finding settlement bookings",
          "url": "https://help.example.com/finding-settlement-bookings"
        }
      ],
      "needsClarification": false
    }
  }
}

MCP Access

MCP allows approved agents to call selected Brainfish tools directly.

The initial MCP integration is read-oriented and includes:

Tool	Purpose
brainfish.search_knowledge	Search approved Brainfish knowledge
brainfish.answer_question	Ask a Brainfish agent for a cited answer

MCP access is permissioned separately from A2A access. Brainfish will only enable MCP tools that have been approved for your workspace.

Example MCP Tool Request

Example input for brainfish.search_knowledge:

{
  "query": "How does settlement booking work?",
  "filters": {
    "collectionIds": ["support"],
    "region": "au"
  },
  "limit": 5
}

Example output:

{
  "results": [
    {
      "title": "Settlement booking overview",
      "summary": "Explains how customers book and manage settlements.",
      "url": "https://help.example.com/settlement-booking",
      "score": 0.87
    }
  ]
}

Authentication

Brainfish supports an API token handshake for customer integrations.

Your Brainfish account team will issue a scoped integration token. Your backend exchanges this token for a short-lived bearer token, then uses the bearer token for A2A and MCP requests.

Token Exchange

POST https://api.brainfi.sh/auth/integration-token/exchange
Content-Type: application/json

{
  "apiToken": "bf_itk_live_xxx",
  "client": "customer-workflow-agent"
}

Example response:

{
  "accessToken": "eyJ...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": [
    "tenant:company",
    "a2a:agent:support",
    "a2a:skill:answer_knowledge_question",
    "a2a:skill:suggest_next_step",
    "mcp:tool:brainfish.search_knowledge",
    "mcp:tool:brainfish.answer_question"
  ]
}

Use the returned bearer token in API requests:

POST https://api.brainfi.sh/a2a/company/support
Authorization: Bearer eyJ...
Content-Type: application/json

Brainfish validates the token, tenant, agent, skill, tool, and data scopes on every request.

Security and Access Controls

Brainfish applies access controls to every A2A and MCP request.

Controls include:

• Tenant isolation.
• Scoped integration tokens.
• Short-lived bearer tokens.
• Agent-level authorization.
• Skill-level authorization.
• MCP tool-level authorization.
• Collection, region, and content-scope restrictions where configured.
• Per-client rate limits.
• Audit logs for external agent activity.

Brainfish does not expose private prompts, model internals, retrieval traces, memory, or unrestricted database access.

Request Access

To request A2A or MCP access, contact your Brainfish account team with the following details:

• Your workspace or tenant name.
• The system or agent that will call Brainfish.
• Whether you need A2A, MCP, or both.
• The Brainfish agent you want to connect to.
• The skills or tools you want enabled.
• Your expected request volume.
• The environment you need access for, such as sandbox or production.
• The technical contact for setup and testing.

Example request:

We would like to enable A2A access for our workflow agent in the Company workspace.

Agent: support
Environment: sandbox
Required A2A skills:
- answer_knowledge_question
- suggest_next_step

Required MCP tools:
- brainfish.search_knowledge
- brainfish.answer_question

Expected volume: 1,000 requests per day
Technical contact: integrations@example.com

What Happens Next

After your request is approved, Brainfish will:

1. Confirm the enabled agents, skills, tools, and environments.
2. Provide your tenant and agent endpoint URLs.
3. Issue a scoped integration token.
4. Confirm rate limits and data scopes.
5. Support a sandbox validation before production use.

Pilot Checklist

Before going live, verify that:

• You can exchange your integration token for a bearer token.
• You can fetch the Brainfish Agent Card.
• Your agent can submit an A2A task.
• Brainfish returns a cited answer or clarification prompt.
• Approved MCP tools work as expected.
• Unauthorized tools or skills are rejected.
• Your team has confirmed expected rate limits and logging requirements.