An MCP (Model Context Protocol) server is a small service that exposes a set of tools, resources, or prompts over a standard protocol. Aperium’s agents call those tools at runtime to read data, run actions, and integrate with whatever system the server is wired to. Anything an agent can do beyond pure reasoning (querying a database, sending an email, looking up a record in your internal app) is, under the hood, an MCP tool call.
Aperium ships with built-in MCP servers for common SaaS systems (Google Workspace, Microsoft 365, Slack, Salesforce, NetSuite, BigQuery, Onyx, and so on). When you have a system that isn’t on that list, the typical answer is: stand up your own MCP server in front of it, and register it in Aperium as a custom integration. The server can be hosted anywhere your agents can reach over HTTPS, and can implement whatever auth model fits your environment (no auth for an internal-only network, or per-user bearer tokens for systems that need user identity).Once you’ve registered a custom MCP server, Aperium’s agents see its tools the same way they see tools from any built-in connector. Permissions, audit logs, and tenant isolation all work the same way too.
If your team wants a deeper, first-party connector — one with a curated tool surface, richer routing, and managed auth rather than a raw remote endpoint — see Build a plugin for the developer path.
There are two places an admin can add a remote MCP server: the Admin Console (any time after first sign-in) and the admin onboarding flow (the first time you sign in).
In the Admin Console, switch to the MCP Servers tab. The tab lists every configured server. Click + Add MCP Server in the top-right corner of the MCP Servers Management panel.Here’s a closer look at the button:
2
Fill in the Basics section
The Basics section describes how the server appears across Aperium.
Display Name. What admins and agent builders see (for example My Amazing MCP).
Name (ID). A short, stable identifier used internally (for example AmazingMCP). Pick something you won’t want to rename later.
Description. Optional one-liner describing what the server is good for.
Enabled toggle. Decides whether the server’s tools load into agent context immediately. Leave it on for normal use; flip it off if you want to register the server but keep its tools out of agent reach for now.
The empty Add New MCP Server dialog.
3
Fill in the Connection section
The Connection section tells Aperium where the MCP server lives and how to authenticate to it.
Supported Template. The auth shape Aperium should use when calling the server. Four templates are admin-selectable:
Remote HTTP - No auth. For servers that live on a private network and don’t require any token. Aperium reaches the server with no Authorization header. Best for in-cluster services that are already protected by NetworkPolicy.
Remote HTTP - User bearer token. Each user stores their own per-user token in Aperium, and Aperium attaches it as a Bearer token. Use this when your MCP server issues its own tokens and expects user identity.
Remote HTTP - Forward user bearer token. Aperium forwards the caller’s own Aperium bearer token straight through to the MCP server, without any separate per-user credential to store. Use this when the server sits behind the same identity provider as Aperium and can validate that token directly.
Remote HTTP - OAuth 2.0 (per user). Aperium runs a full OAuth 2.0 authorization-code flow per user against your provider. This template needs its own field set (see below): OAuth client ID, OAuth client secret, authorize endpoint, token endpoint, and scope. Each user connects once and consents; Aperium manages the resulting tokens.
Remote URL. The MCP endpoint URL. The path usually ends in /mcp (for example https://my-amazing-mcp.com/mcp).
Request timeout (optional). A per-server request budget, in seconds, bounding the initial handshake and each tool call. Leave it blank to use the platform default. The ceiling is 180 seconds — values above it are rejected.
The Add New MCP Server dialog filled out for a User Bearer Token server.
4
For OAuth 2.0 (per user), fill in the OAuth fields
When you choose Remote HTTP - OAuth 2.0 (per user), the form reveals an extra set of fields describing your OAuth provider:
OAuth client ID and OAuth client secret. The credentials Aperium uses to identify itself to your provider.
Authorize endpoint. The URL Aperium sends users to for consent.
Token endpoint. The URL Aperium exchanges the authorization code (and later refreshes) against.
Scope. The space-delimited scopes to request.
Rotating the OAuth client ID, changing the authorize/token endpoints, editing the scope, or changing the remote URL invalidates users’ existing grants — they’ll need to reconnect. Rotating only the client secret keeps grants intact.
5
Click Create
Aperium registers the server against your tenant and reloads the MCP Servers list. For every template except OAuth 2.0 (per user), Aperium also probes the endpoint immediately, so the URL must be reachable when you click Create. OAuth servers can’t be probed until a user connects, so they validate automatically after the first successful connection (or when you use Retry validation).The new server appears with its display name, identifier, status pill, and tool count once tools are discovered. From there it behaves like any other connector: agents can call its tools, the Permissions tab can grant group-level access, and the Pencil icon next to the row lets you edit or rotate settings later.
Every custom MCP server carries a validation status that drives its status pill and decides whether its tools are callable:
Status
What it means
Pending
The server row exists but has never been successfully introspected. No tools are exposed yet.
Validated
The most recent probe succeeded and Aperium has an authoritative tool list. The server is dispatchable and its tools load into agent context.
Error
The most recent probe failed. Any previously cached tool list is treated as stale — the server exposes no callable tools until an admin fixes the configuration and retries.
A server exposes no tools to agents until it reaches Validated. A server that is disabled, pending, or in error still appears on the MCP Servers tab (so you can edit it and retry), but the runtime routes no tool calls to it.
If you’re setting Aperium up for the first time, you can register custom MCP servers during the onboarding flow without leaving it.
1
Click the Remote MCP Servers tile
On the Set your company’s tools screen, click the Remote MCP Servers tile.
The Set your company's tools screen with a Remote MCP Servers tile.
2
Open the Add remote MCP server form
A modal opens listing every custom server you’ve added so far. Click Add remote MCP server to open the form. You can repeat this step to add as many servers as you need.
The Remote MCP Servers modal with an entry to add a new server.
3
Fill in the form
The fields are the same as in the Admin Console flow, with one extra: the onboarding form also accepts a free-form Description that admins and users will see alongside the server.
Display name. Shown across the UI.
Server key. Stable identifier. Use lowercase with underscores (for example customer_data_mcp).
Remote URL. The MCP endpoint, typically ending in /mcp.
Authentication. Pick one of the four templates — No auth, User bearer token, Forward user bearer token, or OAuth 2.0 (per user) — matching what your server expects. OAuth 2.0 (per user) reveals the same client ID/secret, authorize/token endpoint, and scope fields described in the Admin Console flow above.
Description. Optional context shown to admins and users.
The Add remote MCP server form in the onboarding flow.
Click Add server and the server is saved immediately so Aperium can validate the endpoint. When you’re done adding servers, click Done on the previous modal to return to the onboarding flow.
Whether you registered the server through onboarding or the Admin Console, you can edit it at any point from the Admin Console, MCP Servers tab by clicking the pencil icon next to the row. Aperium asks for confirmation before saving changes that would invalidate connected users (for example switching the auth template).Custom servers are non-system, so they can also be deleted from the same row when you no longer need them.