SemAgentAdding tools with MCP
MCP (Model Context Protocol) is an open protocol that lets a service expose its tools through a standard interface. When you add an MCP server, all of that server's tools join the agent's toolset as a ready-made pack — no bespoke integration required.
Catalog or MCP?
Two roads lead to the same place. Choosing between them is simple:
| Connect from the catalog | Add an MCP server by hand | |
|---|---|---|
| Where | Settings → Connectors | Settings → MCP Servers |
| When | The service is in the catalog (e.g. Shopify) | An MCP server that isn't in the catalog |
| Domain permission | Added automatically | Must already be allowed |
| Effort | One click | URL + credentials + risk setting |
If it's in the catalog, connect from the catalog — it's easier and the domain permission takes care of itself. MCP connectors you connect that way also appear on this screen.
Adding a server
Settings → MCP Servers → + Add server. Fill in these fields for each server:
| Field | Description |
|---|---|
| Name | Short and unique, e.g. shopify. |
| Server URL | A Streamable HTTP address starting with https://, e.g. https://.../mcp. |
| Auth secret | Optional. Not the token itself — the secret's name in the Vault, e.g. shopify_token. |
| Capability tier | Which tier the tools count towards (below). |
| Base risk | Determines the approval threshold (below). |
Servers are validated on save. On success the panel tells you: "Tools become available on the agent's next task." New tools do not appear in the middle of a running task; they arrive with the next one.
You can register up to 10 servers.
Capability tier
The tier places the server's tools within the agent's permission hierarchy. Only the tiers enabled for your account can be selected.
| Tier | Scope |
|---|---|
T1 | Reading / research |
T2 | Communication & data (default) |
T3 | System & code |
Base risk
This is the starting risk level for the server's tools; together with your autonomy setting it decides whether approval is required.
| Value | Meaning |
|---|---|
| safe | Side-effect-free reads (catalog search, data reads). Usually runs without approval. |
| low | Low-impact, small reads/writes. |
| medium | External calls / writes — moderate impact. Requires approval in supervised mode. Default. |
| high | Sensitive or irreversible operations. Almost always asks for approval. |
Choose the risk level according to real impact. Marking a server that writes data as safe means closing the approval gate with your own hand. When unsure, leave it at medium.
Authentication
If the server needs a token, do not type it on this screen. Instead:
- Go to the Agent Vault and save the token under a name (e.g.
shopify_token). - On the MCP screen, enter that name in the Auth secret field.
At execution time the system injects the token as an Authorization: Bearer … header. The raw value is never sent to the AI model.
Domain permission (egress) — the usual stumbling block
For security, the agent may only reach domains the administrator has allowed, and only over public https addresses.
A domain that is not on the allow-list cannot be saved. You'll see: "…is not on the egress list allowed by your administrator. Ask your administrator to add this domain." This is a hard rule that rejects the record — it cannot be waved through with an approval.
Local and private network addresses (localhost, 10.x, 192.168.x …) are also rejected as SSRF protection. The server must live at a publicly reachable https address.
Domains get onto your list in two ways:
- You connect a connector from the catalog — the domain is added automatically.
- The platform administrator adds it manually. There is no tenant-side screen for adding one.
Don't confuse this with tool calls. If a tool like http_request targets a domain outside the allow-list, the request is not blocked — it goes to approval. Registering an MCP server, by contrast, is rejected outright. Two different layers, two different behaviours.
Verifying the connection
For MCP connectors connected from the catalog, the Test button on the card connects to the server and lists the tools it finds. It's the fastest way to confirm the server responds and to see what it offers.
Common causes of a failing test: the URL isn't a Streamable HTTP endpoint, the token is invalid or expired, or the server doesn't return tools/list in the expected shape.
The tools arrived — what now?
MCP tools are not privileged. Every call passes through the same gates as built-in tools:
- Permission: is the tool in a tier enabled for your account?
- Approval: is its risk level above your autonomy threshold? If so, an approval card appears.
- Quarantine: external content coming back from the server is filtered before it reaches the planner (prompt-injection defence).
Details: Autonomy & approvals and Security architecture.