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 > Agents > Agent Toolkit > 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)

Expect a pause. Loading a server’s tools asks the server what it can do, which can take several seconds — that’s why you click Load Tools yourself rather than the page probing every server for you.

The MCP Servers page

┌────────────── Studio > Agents > Agent Toolkit > MCP Servers ─────────────────┐
│ ┌─ Servers (L2) ──────────┐ │ ┌─ Detail (right pane) ─────────────────────┐ │
│ │  GitHub MCP        ─────┼─┼─│ ● GitHub MCP   [HttpSse]  [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 ]                            │ │
│ └──────────────────────────┘ │ └────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────┘
   ● green = active   ● grey = inactive (status dot, on the detail header)

Left (L2 list) — every MCP server registered for this project, by name. The footer Add MCP Server button opens the registration dialog. A platform admin can also register servers for everyone at Administration > Extensions > MCP Servers — those show up here as read-only.
Right (detail pane) — the selected server. Its header carries a status dot (green when the server is marked Active, grey when it isn’t), the name, a transport badge, 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	Green when the server is marked Active, grey when it isn’t	Set in the Add/Edit dialog’s Active toggle
Transport badge	The protocol used to reach the server	One of the three transports you picked at registration
Scope badge	Where this server comes from	Managed by platform / From Environment / From Subscription (i.e. registered for your whole workspace) — see below
⋮ → Edit / Delete	Edit settings or remove the server	Disabled for any server that came from above your project (hover for the reason)
Load Tools	Connects to the server and asks it what tools it has	This is where the pause happens
Tool checkbox	Whether agents attaching this server can see this tool	Every box starts ticked; untick the ones you want hidden (see the walkthrough)
Save filter	Persists your tool selection	Appears only when the selection has changed 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 (i.e. registered for your whole workspace). 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 > Agents > Agent Toolkit > 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 with every box ticked and the counter reading “9 of 9 enabled” — an unfiltered server exposes everything it has.
Untick everything except the two tools you actually want — e.g. leave search_issues and get_file ticked. The counter falls to “2 of 9 enabled”, and the hint under the list says the same thing in one line: uncheck a tool to hide it from agents that attach this server.
Click Save filter. Your agents that use this server will now see only those two tools.

Tip — an empty selection means everything. Unticking the boxes one by one is fine, but untick the last one and the selection is empty again — which the platform reads as “no filter”, so all the tools come back. Always leave at least the tools you want ticked, then Save filter.

Watch out. A discovered tool might be destructive (delete_repo, drop_table). The filter is your safety gate, and it starts wide open — untick anything dangerous and Save filter before you attach the server to an agent. Then layer an approval on the agent side (Guard rails, 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 (local process) / WebSocket. Drives which connection field shows next
Server URL	The server’s endpoint URL	Required for HTTP + SSE and WebSocket transports
Stdio Command	The command line that launches a local server process	Required for Stdio (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 names every missing or malformed field at once — a name, a valid Server URL, a Stdio command — and marks them inline rather than stopping at the first one. A name already in use is refused too

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 name and scope badge, with a × to remove it again.
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”.

What ships when you publish. When you package an agent into a Hub solution (V4), only the requirement travels — “this agent needs a GitHub MCP server”. The endpoint and credentials never do. Whoever installs the package supplies their own server and secrets, so treat MCP credentials as local to this environment.

Try it yourself

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

Studio > Agents > Agent Toolkit > 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 → untick everything except 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 asks the server what tools it has — expect a short pause. Everything arrives ticked; untick what you don’t want and Save filter. An empty selection exposes all tools.
Scope badges (Managed by platform / From Environment / From Subscription — i.e. your whole workspace) mark servers you can use but not edit/delete.
Attach a server on the agent’s Capabilities tab. On publish only the requirement travels — 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.