Getting Started

Attach a Gateway to an MCP server

Attach a reusable Gateway to an MCP server, understand the public URL that attachment creates, and verify the runtime requirements.

4 sections

Attaching a Gateway binds one reusable auth profile to one MCP server.

That attachment creates the public MCP route identity used by:

  • the public MCP URL
  • OAuth discovery documents
  • the authorize, token, and callback endpoints
  • request logs and downstream grants

In the wizard#

If you are creating a new server:

  1. Open Create Server.
  2. Import the API and select tools.
  3. In Authentication, choose OAuth 2.0.
  4. Select an existing Gateway or create a new one inline.
  5. Finish the wizard.

On an existing server#

  1. Open MCP Servers.
  2. Open the server.
  3. Open the Gateway tab.
  4. Click Attach Gateway.
  5. Pick the Gateway profile and save.

The server detail page then shows:

  • the attached Gateway
  • the public MCP URL
  • the protected-resource metadata URL
  • the downstream auth profile
  • the Gateway-wide allowed scope set that server can request from

What must be true for Gateway-backed servers#

The public URL is owned by Gateway.

For servers generated with @emcy/openapi-to-mcp, Emcy can derive the necessary Gateway-facing configuration for you.

For self-hosted runtimes, FastMCP runtimes, and raw MCP SDK servers, the product model is simpler:

  • exposes MCP over Streamable HTTP
  • remains a normal MCP runtime
  • lets Gateway own the public MCP URL, auth edge, and grant/policy layer

For today's private worker flow, the runtime also needs to accept Gateway's worker secret and forwarded access token headers. The FastMCP sample shows that minimal adapter.

If you attach the same Gateway to multiple servers, each server can still request a different subset of that Gateway's allowed scopes. What stays shared is the auth boundary itself: auth server, client ID, resource, and identity model.