MCP servers

In one line. Register an external MCP server so your agents can use the tools it exposes, and curate exactly which of those tools they are allowed to call. You’ll be able to. Add an MCP server, discover its tools, filter the list down to the ones you want, and attach it to an agent. Where this lives. Studio ▸ Agent Builder ▸ MCP Servers (/studio/.../agent_builder/mcp_servers).

Why it matters

A custom API tool (A5 · Tools & functions) plugs in one function — you register its URL and input schema by hand, one tool at a time. An MCP server plugs in a whole set of tools at once.

MCP (Model-Context-Protocol) is an open standard for tool servers. Plenty of off-the-shelf servers already exist — for GitHub, Jira, a filesystem, a web-search provider, an internal service your team wrote. Each one exposes a menu of tools over a standard protocol. Register the server once and the platform asks it what tools it has (this is tool discovery), then lets you pick which of them your agents may use. You don’t hand-write a schema per tool — the server describes them for you.

This page is about agents consuming MCP servers as capabilities. The flip side — external tools driving Botminds over MCP — lives at V2.

When to use which:

	Custom API tool (A5)	MCP server (this page)
You have…	one HTTP endpoint you control	an existing MCP-speaking server, often third-party
You register…	one tool, schema by hand	a server; its tools are auto-discovered
Number of tools	one per registration	many, from one registration — filter to taste
Reach for it when	a single bespoke call	a ready-made toolset (GitHub, search, files, a partner)

Under the hood. When you connect, the platform calls the server’s list_tools to enumerate its tools. Today that discovery is eager — it happens on connect and can take several seconds per server (roughly ~20 s for a slow one), which is why the page makes you click Load Tools explicitly rather than probing every server automatically. A lazy, cached discovery is in design but not what ships today; plan for a short pause when you load a server’s tools.

The MCP Servers page

┌──────────────────── Studio ▸ Agent Builder ▸ MCP Servers ────────────────────┐
│ ┌─ Servers (L2) ──────────┐ │ ┌─ Detail (right pane) ─────────────────────┐ │
│ │  GitHub MCP        ● ────┼─┼─│ ● GitHub MCP   [HTTP+SSE]  [From Environ.] │ │
│ │  Web Search        ○     │ │ │                                    ⋮ menu  │ │
│ │  Filesystem        ●     │ │ │  Tools  (3 of 9 enabled)      [Save filter]│ │
│ │                          │ │ │  ┌────────────────────────────────────────┐│ │
│ │                          │ │ │  │ [x] search_issues Find issues by query ││ │
│ │                          │ │ │  │ [x] create_issue  Open a new issue     ││ │
│ │                          │ │ │  │ [ ] delete_repo   Delete a repository  ││ │
│ │                          │ │ │  │ [x] get_file      Read a file's content││ │
│ │                          │ │ │  └────────────────────────────────────────┘│ │
│ │  [ Add MCP Server ]      │ │ │  [ Load Tools ]                            │ │
│ └──────────────────────────┘ │ └────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────┘
   ● = active   ○ = inactive (status dot)

Left (L2 list) — every MCP server registered for this project, with a status dot (filled ● = active, hollow ○ = inactive). The footer Add MCP Server button opens the registration dialog.
Right (detail pane) — the selected server. Its header carries the status dot, the name, a transport badge (e.g. HTTP+SSE), and a scope badge. The ⋮ action menu holds Edit and Delete.
Tools section — the heart of the page: a Load Tools button, then a checklist of the server’s discovered tools (each a checkbox + name + description), an “n of m enabled” counter that updates live, and a Save filter button that appears when you’ve changed the selection.

What every control does

Control	What it does	Notes
Status dot (●/○)	Shows whether the server is marked Active	Set in the Add/Edit dialog’s Active toggle
Transport badge	The protocol used to reach the server	`HTTP+SSE`, `Stdio`, or `WebSocket`
Scope badge	Where this server comes from	Managed by platform / From Environment / From Subscription — see below
⋮ → Edit / Delete	Edit settings or remove the server	Disabled for platform-/environment-/subscription-scoped servers (hover for the reason)
Load Tools	Connects to the server and discovers its tools via `list_tools`	The deliberate pause from the under-the-hood note happens here
Tool checkbox	Include this tool in the agent-visible set	Empty selection means all tools are exposed (see the walkthrough)
Save filter	Persists your tool selection	Appears only when the selection is dirty and the server isn’t locked by scope

Scope, and why some servers are read-only. A server can be defined at a level above your project — Managed by platform, From Environment, or From Subscription. You can use those servers and pick their tools, but you can’t Edit or Delete them (the menu items are disabled with a tooltip explaining why). Only servers you registered at the project level are fully editable.

The tool states you’ll see

When you click Load Tools, the section shows one of:

Loading — discovery in progress (the pause).
Connection error — the server couldn’t be reached or rejected your credentials. Re-check the URL/command and auth in Edit.
No tools — connected, but the server advertises nothing.
Idle — before you’ve loaded, it reads “Click Load Tools…”.
Loaded — the checklist, ready to filter.

Walkthrough — register a server and expose two of its tools

Open Studio ▸ Agent Builder ▸ MCP Servers.
Click Add MCP Server (footer). The Add dialog opens (next section). Fill it in and Save.
Back on the page, select your new server in the left list.
Click Load Tools. Wait out the discovery pause; the tool checklist appears.
The counter reads, say, “0 of 9 enabled”. Tick the two tools you actually want — e.g. search_issues and get_file. The counter updates to “2 of 9 enabled”.
Click Save filter. Your agents that use this server will now see only those two tools.

Tip — empty filter means everything. If you leave every box unchecked and don’t filter, the server exposes all its tools. Filtering is opt-in to a subset — so always tick the few you want and Save filter rather than relying on “I unchecked the rest”.

Watch out. A discovered tool might be destructive (delete_repo, drop_table). The filter is your safety gate — leave dangerous tools unchecked. Then layer an approval on the agent side (Guard rails and governance, A8) for anything that writes.

The Add / Edit dialog

The registration form, field by field:

Field	What it does	Notes
Name	Display name in the list and on the agent’s card	Required
Description	Free-text note on what the server is for	Optional
Transport Type	How the platform reaches the server	One of HTTP+SSE / Stdio / WebSocket. Drives which connection field shows next
Server URL	The server’s endpoint URL	Shown for HTTP+SSE and WebSocket transports
Stdio Command	The command line that launches a local server process	Shown for Stdio transport (e.g. an `npx …` launcher)
Auth Type	How to authenticate to the server	None / Bearer Token / API Key — drives the credential fields below
Bearer Token	The bearer secret	Shown when Auth = Bearer Token; masked
Header name + value	A custom auth header and its secret	Shown when Auth = API Key; value masked
Active	Whether the server is enabled (drives the status dot)	Toggle
Test Connection	(Edit mode only) Connect now and report the result	Shows Connected — N tools with tool chips, or the error
Cancel / Save (or Update)	Discard / persist	Save is disabled while the form is invalid or saving

Tip. In Edit mode, run Test Connection before you save — it confirms the URL and credentials work and previews the tool count, so you’re not loading a dead server later.

Attaching an MCP server to an agent

You don’t run tools from this page — you make the server available, then wire it onto an agent. In the Agent editor, open the Capabilities tab (recap in A3 · Your first agent):

Find the MCP servers section on the Capabilities tab.
Click + Add MCP server. The menu lists your registered servers, each tagged with its scope badge (so you can tell a project server from a platform/environment one).
Pick the server. It appears as a card showing its status dot, URL/command, and transport.
Save Agent.

The agent now sees the tools you filtered to on the MCP Servers page — no more, no less. That filter is the contract between “what the server can do” and “what this platform exposes”.

Coming soon / by design — publishing. When you package an agent into a Hub solution (V4), its MCP servers travel as a DECLARE: the requirement (“this agent needs a GitHub MCP server”) ships, but the endpoint and credentials never do. Whoever installs the package supplies their own server and secrets. Treat MCP credentials as environment-local — they stay put.

Try it yourself

Wire a real MCP server onto an agent end-to-end:

Studio ▸ Agent Builder ▸ MCP Servers → Add MCP Server.
Name it (e.g. “Web Search”), choose a Transport Type, fill the Server URL (or Stdio Command), set Auth Type + credentials if the server needs them, leave Active on, Save.
(Optional, edit mode) Test Connection — confirm Connected — N tools.
Select the server → Load Tools → tick two tools → Save filter. Confirm the counter reads “2 of N enabled”.
Open an agent → Capabilities tab → MCP servers → + Add MCP server → pick it → Save Agent.
In the agent’s Playground, ask something that needs one of those two tools and watch the tool call fire. Confirm the other (unticked) tools never appear.

Recap

An MCP server plugs a whole set of external tools into your agents over a standard protocol — reach for it over a custom API tool (A5) when a ready-made toolset exists.
Register one with Add MCP Server: Name, Transport Type (HTTP+SSE / Stdio / WebSocket), the matching Server URL or Stdio Command, Auth Type (None / Bearer / API Key) + credentials, and Active.
Load Tools discovers the server’s tools (an eager list_tools — expect a short pause). Tick the ones you want, Save filter; an empty filter exposes all tools.
Scope badges (Managed by platform / From Environment / From Subscription) mark servers you can use but not edit/delete.
Attach a server on the agent’s Capabilities tab. On publish, MCP travels as a DECLARE — the endpoint and credentials never ship.

Where to go next

Guard rails — constrain what an agent does with the tools you’ve just given it.
Tools & functions — the single-endpoint alternative, for when you don’t have a whole MCP server.
Botminds as an MCP server — the flip side: external tools driving Botminds over MCP.
Hubs & solutions — how MCP servers (and their missing credentials) behave when you package and ship a solution.