Connecting your systems (MCP)

BrainStack's agent reaches your company systems — ticketing, workforce analytics, whatever you expose — over the open Model Context Protocol. A new integration is a new server URL, not new BrainStack code.

The shape of a Company MCP Server

One HTTP service, speaking MCP over the streamable-http transport at a single endpoint (we use /mcp), stateless per call. It advertises tools; BrainStack discovers them and lets the agent call them mid-answer. Our reference server exposes three:

list_tickets    — list support/engineering tickets, filter by assignee
assign_ticket   — assign or reassign a ticket to an employee   (mutating)
get_analytics   — workload and resolution metrics for the team

Build yours with any MCP SDK (the official Python mcp package's FastMCP, for instance) — if it serves streamable-http and lists tools, it plugs in.

Authentication: a shared secret, server-to-server

The browser never talks to your MCP server and never holds its secret. Every request comes from the BrainStack backend and carries three headers your server must validate:

X-MCP-Secret:  <shared secret>     reject the request if it doesn't match
X-Tenant-Id:   <workspace id>      scope every read and write to this tenant
X-Role:        <employee|manager|admin>

Validate the secret on every call, scope all data by X-Tenant-Id, and re-check X-Role before any mutating tool — defense in depth, even though BrainStack already gates by role upstream.

Role gating — absent by construction

When a manager or adminasks a question, their agent session discovers your server's tools and can act with them. An employee'ssession never connects to the server at all — the action tools don't exist in their agent's world. Not blocked by a prompt that could be talked around; absent by construction. The same rule applies to API keys: only keys granted the actions:write scope get tools discovered (see the API reference).

Discovery and health

BrainStack discovers your tool catalog and caches it for about five minutes; the Connections page shows exactly what the current session sees, and its Refresh button re-discovers on demand — waking a sleeping server first if yours idles. Keep an unauthenticated /health endpoint next to /mcp for that.

Wiring it up

Two settings on the BrainStack backend connect your server:

COMPANY_MCP_URL     = https://your-company-systems.example.com/mcp
MCP_SHARED_SECRET   = <the same secret your server validates>

If they're unset or your server is unreachable, nothing breaks — the agent simply runs with its native tools and Connections shows the honest state.