Custom MCP server

Your team runs MCP servers the catalog doesn't list, such as an internal tool or a vendor server too new to have a catalog entry. Add one as a custom server and it gets the same treatment as a catalog resource: each of its tools sits behind a policy rule and each call lands in the audit log. A custom server also takes request headers and can receive the calling user's identity, which catalog resources can't.

Add a custom serverCopy Anchor Link

1. Navigate to Tools & Services, click Add Resource, then + Custom server
2. Enter a display name, a slug, and the server URL for the MCP server. The slug is the short identifier used in policies (mcp.slug == "…") and when scoping a connection to one MCP.
3. Under Authentication, choose whose access the agent's tool calls run with:
   • Users sign in themselves – each user signs in to the server once with their own account. Register automatically registers an app with the provider for you (dynamic client registration, DCR) and needs no credentials. Use your own app takes your client ID, secret, and scopes, plus the endpoints: an issuer URL, or an authorize URL and a token URL
   • Enterprise-managed – users get access through your organization's SecureAuth Connect sign-in, with no sign-in screen. Enter the app's client ID, secret, and scopes, plus the endpoints. See Enterprise-managed authorization for the prerequisites.
   • OAuth app – the gateway signs in as its own app (client credentials), and every user shares that access. Enter the client ID, secret, scopes, and an issuer URL or token URL
   • API key – headers sent with every request, shared by every user
   • No authentication – the server needs no credentials
4. Add any headers the server needs
5. Optionally add a description and an icon
6. Click Add

The gateway connects to the server and discovers available tools automatically.

Give it an iconCopy Anchor Link

To give the server an icon, select the tile beside Display name, either when you add the server or after you choose Edit on it. Use a PNG, JPEG or WebP file of up to 1 MB. The gateway scales an image over 512 pixels on a side down to fit. Select Remove in the same menu to go back to the generic icon. You see the tile when you have the Upload images permission. Catalog resources keep their brand logo.

HeadersCopy Anchor Link

A custom server can take request headers that the gateway sends with every call, such as a tenant ID, a routing key, or an API key under its own name. They also let you secure an internal server at the network level: put it behind a proxy or firewall that requires a secret header, give that header to the gateway, and only calls through Agent Authority get through. Add them in the Headers section of the Settings tab, or inside Authentication with API key.

See Propagate request headers for the setup, reserved names, limits, and how values are stored.

User identityCopy Anchor Link

A custom server often needs to know the person behind a call, to scope results or log the caller. Switch on Send user identity on the Settings tab, and the gateway tells the server on every call, in one of two ways:

• User identity assertion – a signed token in the X-SecureAuth-Jwt-Assertion header, which your server verifies before it trusts the person. See User identity assertion.
• User identity headers – the same person as plain X-SecureAuth-User- headers, for a server or proxy that can't verify a token. Trust them only behind a channel check, such as a network allowlist or mutual TLS. See User identity headers.

Prefer the assertion. Only custom servers support either, and the gateway requires an https server URL.

Change a custom server laterCopy Anchor Link

Custom servers stay editable. On the detail page, Edit changes the display name, description, slug, and server URL. If the gateway registered the app automatically, the server URL can't change: to target another server, delete the custom server and add it again. The Settings tab holds everything about authentication: the option you chose, the client credentials, the endpoints, the scopes, and the headers. Leave a secret or a header value blank there to keep the stored one.

Token endpoint authenticationCopy Anchor Link

By default the gateway auto-detects how to send the OAuth2 client credentials to the provider's token endpoint. Some providers only accept credentials in the POST body and reject HTTP Basic authentication. Combined with single-use authorization codes, auto-detection can make the connect flow fail.

For dynamically registered (DCR) servers this is fully automatic: the gateway uses the method the provider reports during registration, and the setting cannot be overridden.

When you bring your own client (a custom server with existing credentials, or a catalog integration in BYO mode), set Token Endpoint Authentication explicitly if the provider is strict: client_secret_basic (client secret in the HTTP Basic header), client_secret_post (client secret in the POST body), or none (public client).

Next stepsCopy Anchor Link

Your server's tools now go through the gateway, and if you switched on user identity, your server knows which person each call comes from. Decide which agents may call which of those tools in Policies, matching the server by its slug.

• Manage your MCP servers – describe, inspect, and track changes to the servers you added
• Connect an agent – scope a connection to this one server