MCP Gateway

Aggregate Model Context Protocol servers behind one endpoint with toolkit scoping, upstream authentication, and OAuth2 for agents

Beyond LLM traffic, TrustGate runs a dedicated MCP Gateway (:8082) that fronts Model Context Protocol servers. Rather than connecting an agent to each MCP server directly, TrustGate aggregates several servers into a single MCP endpoint. It composes their tools, prompts, and resources, then applies tenancy, access control, authentication, and observability.

The TrustGate data plane must reach each MCP registry url. SaaS cannot call private VPC endpoints unless you expose them. Use Hybrid for internal MCPs.

One endpoint, many servers

An agent connects to one TrustGate MCP endpoint and sees a unified surface. TrustGate speaks JSON-RPC over the streamable-http transport and implements the standard methods:

Method	Returns
tools/list · tools/call	The composed tool catalog, and tool invocation.
resources/list · resources/templates/list · resources/read	Composed resources and templates.
prompts/list · prompts/get	Composed prompts.

Behind the endpoint, each upstream is an MCP registry (type: MCP). TrustGate fans list calls out to the bound registries, merges the results, and routes each call/read/get to the owning server.

Tool name composition

Because two servers can expose the same tool name, TrustGate keeps names unique on the merged surface:

• Unique names pass through unchanged.
• On a collision, the tool is prefixed with the registry name (e.g. asana_create_task).
• If that still collides, a short registry id is added; as a last resort a numeric suffix.

So an agent always sees stable, unambiguous names regardless of how many servers are behind the endpoint.

Registering an MCP server

Connect MCP servers from the console:

1. Open TrustGate → Registry → MCP.
2. Pick a catalog server (one-click when no extra config is needed) or Add custom. For a remote MCP server, paste the server URL. To expose a REST API instead, set Source to OpenAPI document and follow OpenAPI tools.
3. For MCP URLs: configure transport (streamable HTTP), static headers, and upstream auth. For OpenAPI: the document URL, then Validate OpenAPI.
4. Select Test connection (MCP URL) or complete validation (OpenAPI), then Connect / Save.
5. Open the registry to browse live tools the server exposes.

Setting	Meaning
Catalog code	Join key used when a catalog server is already connected (empty for custom URLs).
URL	The MCP server’s http(s) endpoint.
OpenAPI spec URL	An OpenAPI 3 document to turn into tools instead of a server URL.
Transport	Streamable HTTP (MCP server URLs only).
Headers	Static headers sent upstream.
Auth	How TrustGate authenticates to the server (see below). An OpenAPI backend supports None, Static header, and OAuth2 client credentials.

Toolkits and capability scope

A consumer does not automatically get every tool on every bound server. Access is governed by a toolkit, which lists grants that scope a registry to specific tools, prompts, or resources:

Entry field	Meaning
registry_id	Which MCP registry the grant applies to.
tool / prompt / resource	The capability name to allow; * grants all of that kind.
expose_as	Optional rename for how the capability appears to the agent.

For inline MCP consumers, the toolkit lives on the consumer (mcp.toolkit). For role-based consumers, the effective view is built from the matched roles:

• Registries = the union of the matched roles’ MCP registries.
• Toolkit = the union of the roles’ mcp_policies toolkits. A role that binds an MCP registry without an explicit toolkit grants that server fully.

So one MCP endpoint can present a different, identity-scoped toolkit to each caller.

Fail mode

fail_mode decides what happens when an upstream server is unavailable:

• open: skip the failed server.
• closed: fail the call.

For role-based consumers, the effective mode is open only when every contributing role declares it open; otherwise it is closed (and closed when no role grants access).

Upstream authentication

mcp_target.auth.mode controls how TrustGate authenticates to the MCP server. Each mode has its own requirements:

Mode	Behavior	Requires
none	No upstream authentication.	None
static	A fixed header/token on every call.	header + value.
client_credentials	Client-credentials token fetch, then attach the access token.	client_id, client_secret, token_url. Supported for MCP URL and OpenAPI sources.
passthrough	Forward the caller’s own bearer token unchanged.	expected_audience (unconstrained passthrough is rejected); the caller’s token audience must match. MCP URL sources only.
exchange	Exchange the caller’s token for a downstream one (STS).	a pattern (see below). MCP URL sources only.
forwarded	Use a per-user credential the user authorized once (OAuth connect).	provider + registration config. MCP URL sources only.

Exchange patterns

The exchange mode implements standard token-exchange patterns:

Pattern	Requires
impersonation	audience
delegation	audience + actor
obo (on-behalf-of)	scope (e.g. resource/.default)
token_exchange	audience

Forwarded (per-user OAuth)

For SaaS servers where each end-user must connect their own account (e.g. their Asana), forwarded mode stores a per-user OAuth credential:

• Set provider and either registration: auto (TrustGate registers the client) or registration: manual with client_id, authorize_url, and token_url.
• The first call for a user with no stored credential returns a consent-required signal with a connect link; the user authorizes the provider once and the credential is vaulted.
• TrustGate refreshes expiring credentials automatically and re-prompts for consent only when a grant can no longer be refreshed.

Agent authentication

The MCP Gateway is itself an OAuth2 authorization server for the agents connecting to it, implementing the standard discovery and flow endpoints:

Endpoint	Purpose
/.well-known/oauth-protected-resource	Protected-resource metadata.
/.well-known/oauth-authorization-server	Authorization-server metadata.
/register	Dynamic Client Registration (DCR).
/authorize · /callback · /token	Authorization-code flow with PKCE.
/.well-known/jwks.json	Public keys for token verification.
/connect · /disconnect	Connect/disconnect an agent’s link to a downstream provider (the consent flow used by forwarded auth).

Together these let an agent register, obtain a token, call the unified MCP endpoint, and complete a one-time connection when a downstream service requires per-user authorization.

Connect an agent

All clients use the same endpoint for a given consumer. The consumer’s Connect tab provides Cursor, Claude Code, and generic JSON snippets.

Agent	Page
Claude Code CLI	Claude Code
Claude organization connector (claude.ai, Desktop, Cowork, Claude Code)	Claude Enterprise
Cursor	Cursor
OpenAI Codex	Codex
VS Code / GitHub Copilot	GitHub Copilot
Microsoft Copilot Studio	Copilot Studio

Do not use a TrustGuard collector tgk_… as an MCP credential.

Related

• OpenAPI to MCP: expose REST API operations as tools
• Okta · Entra ID