--- title: "Connect your agents to Brainfish with A2A and MCP" description: "Brainfish supports enterprise agent integrations using Agent2Agent (A2A) and Model Context Protocol (MCP)." canonical_url: "https://help.brainfi.sh/articles/connect-your-agents-to-brainfish-with-a2a-and-mcp-VoeNdwlgoL" md_url: "https://help.brainfi.sh/articles/connect-your-agents-to-brainfish-with-a2a-and-mcp-VoeNdwlgoL.md" --- # 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: ```text https://api.brainfi.sh ``` Your exact tenant and agent slugs are provided after access is approved. Example A2A base URL: ```text https://api.brainfi.sh/a2a/{tenantSlug}/{agentSlug} ``` Example MCP base URL: ```text 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: ```text 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: ```json { "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 ```json { "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: ```json { "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`: ```json { "query": "How does settlement booking work?", "filters": { "collectionIds": ["support"], "region": "au" }, "limit": 5 } ``` Example output: ```json { "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 ```http POST https://api.brainfi.sh/auth/integration-token/exchange Content-Type: application/json { "apiToken": "bf_itk_live_xxx", "client": "customer-workflow-agent" } ``` Example response: ```json { "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: ```http 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: ```text 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.