Getting Started

Share one Gateway across multiple MCP servers

Use one Gateway for multiple MCP servers when they share the same downstream auth boundary, while still requesting different scope subsets per server.

6 sections

You do not need one Gateway per MCP server.

If two MCP servers sit in front of the same downstream OAuth system, use the same Gateway and let each server ask for the scope subset it actually needs.

This is the common shape when:

  • one product API is split into multiple MCP surfaces
  • one support server and one operations server both call the same downstream API
  • one Host runtime and one self-hosted runtime both rely on the same auth provider

The rule#

One shared Gateway works when these stay the same:

  • downstream authorization server
  • downstream client ID
  • downstream resource or audience
  • same-user identity resolution rules

What can differ by server or client flow is the requested scope subset.

In practice, the Gateway holds the full allowed scope set, and each attached MCP server can request only the smaller subset it needs during authorization.

If your clients do not request scopes explicitly, Emcy falls back to the full allowed Gateway scope set.

Example#

Imagine you have one API and two MCP servers:

  • support-assistant
  • ops-console

Both use:

  • the same auth server
  • the same downstream client ID
  • the same downstream API audience

Your shared Gateway might allow this full set:

TEXT
tickets.read tickets.write accounts.read admin.read

Then each server can ask for less:

  • support-assistant requests tickets.read accounts.read
  • ops-console requests tickets.write admin.read

That keeps one Gateway profile, one public auth edge, and one grant-brokering layer, without forcing every flow to ask for every scope every time.

[PLACEHOLDER - TODO - image caption: Two MCP servers attached to one shared Gateway, with one authorization flow requesting support scopes and the other requesting operations scopes.]

How to set it up#

  1. Create one Gateway with the union of scopes either MCP server may need.
  2. Attach that same Gateway to both MCP servers.
  3. Make each client flow request only the scopes needed for that server.
  4. Test each server independently from Agent, Embed, or your MCP client.

When not to share a Gateway#

Create a second Gateway if either server needs a different:

  • downstream client ID
  • resource or audience
  • identity resolution strategy
  • authorization server

Those are different auth boundaries. They should not be forced through the same Gateway profile.

Why this pattern is useful#

This is the simplest way to keep your Gateway model clean:

  • build MCP runtimes however you want
  • share one public auth edge where the boundary is actually shared
  • keep scope requests minimal per MCP surface

That is usually better than cloning nearly identical Gateways for every server.