> ## Documentation Index > Fetch the complete documentation index at: https://neuraltrust-92b43583-develop.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://modelcontextprotocol.io) 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](/neuraltrust/deployment/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](/trustgate/concepts/registries) (`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](/trustgate/mcp/openapi). 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](/trustgate/concepts/consumers) MCP consumers, the toolkit lives on the consumer (`mcp.toolkit`). For [role-based](/trustgate/concepts/roles) 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](/integrations/claude-code#connect-to-trustgate) | | Claude organization connector (claude.ai, Desktop, Cowork, Claude Code) | [Claude Enterprise](/integrations/claude-enterprise#organization-connectors) | | Cursor | [Cursor](/integrations/cursor) | | OpenAI Codex | [Codex](/integrations/codex) | | VS Code / GitHub Copilot | [GitHub Copilot](/integrations/github-copilot) | | Microsoft Copilot Studio | [Copilot Studio](/integrations/copilot-studio) | Do not use a TrustGuard collector `tgk_…` as an MCP credential. ## Related * [OpenAPI to MCP](/trustgate/mcp/openapi): expose REST API operations as tools * [Okta](/trustgate/concepts/authorization/okta) · [Entra ID](/trustgate/concepts/authorization/entra-id)