Getting Started

Create a Gateway

Create a reusable Gateway auth profile, understand what it owns, and know when to reuse one Gateway across many MCP servers.

4 sections

A Gateway is Emcy's reusable public auth edge for MCP.

One Gateway stores the downstream OAuth profile once, then you can attach it to one or many MCP servers.

You do not need a Gateway for every embedded agent.

You need one when an attached MCP server uses user-scoped OAuth or needs a reusable public MCP auth surface.

What a Gateway owns#

A Gateway owns:

  • the downstream authorization server URL
  • the downstream client ID
  • the downstream resource or audience
  • downstream scopes
  • client registration behavior
  • identity resolution settings for same-user auth
  • downstream grant brokering and request logs

A Gateway does not own:

  • the MCP runtime process
  • agent-specific model spend surfaces

Those belong to Host and Agent respectively, even though Gateway remains the auth and policy edge.

Create a Gateway in the dashboard#

  1. Open Gateways.
  2. Click Create Gateway.
  3. Enter a name your team will recognize.
  4. Fill the downstream OAuth fields.
  5. Save.

After save, the Gateway is ready to attach to MCP servers.

When to reuse a Gateway#

Reuse one Gateway when multiple MCP servers talk to the same downstream auth system and should share the same public OAuth profile.

Good examples:

  • one product API split into several MCP servers
  • one app with separate support and operations MCP surfaces
  • one self-hosted runtime and one Host runtime that both rely on the same downstream auth server

Those servers can still request different scope subsets, as long as they all fit inside the Gateway's allowed scope set.

Example:

  • the shared Gateway allows tickets.read tickets.write admin.read
  • the support server requests tickets.read
  • the operations server requests tickets.write admin.read

Create a separate Gateway when the downstream auth profile is materially different:

  • different client ID
  • different resource or audience
  • different scopes
  • different identity resolution rules