Getting Started

Add OAuth to your MCP server

Configure a reusable Emcy Gateway, attach it to your MCP server, and understand how Emcy brokers user-scoped OAuth for MCP clients.

7 sections2 locales

This page is about MCP client authentication: how Emcy, ChatGPT, VS Code, or another MCP client gets a token before calling your MCP server.

If your tools act on user-scoped data, choose OAuth 2.0.

Keep these roles separate#

When you configure OAuth in Emcy, separate these concerns:

  • Authorization server: issues tokens
  • Protected resource: your MCP server
  • MCP client: Emcy agent, embedded SDK, ChatGPT, VS Code, or another client
  • Upstream API auth: how your MCP server talks to the real API after it has a valid user token

The canonical example is the Todo sample app. The implementation and validation contract live in docs/e2e-oauth-mcp-todo-demo.md.

Create or update the server#

If you are creating a new server:

  1. Open the server wizard.
  2. Go to Authentication.
  3. Select OAuth 2.0.
  4. Select an existing Gateway, or create a new one inline.
  5. Finish the wizard.

If the server already exists:

  1. Open MCP Servers.
  2. Open the server.
  3. Open the Gateway tab.
  4. Attach a reusable Gateway or follow the link to create one.
  5. Save and regenerate if the runtime contract changed.

Fields that matter#

Authorization Server URL#

Use the issuer or metadata root for the server that issues tokens.

Examples:

  • https://your-tenant.auth0.com
  • https://auth.example.com/.well-known/oauth-authorization-server

Authorization Server Metadata URL#

Set this only when discovery needs an explicit metadata URL override.

Login URL or Authorization Endpoint#

This is the popup entry point for interactive sign-in.

Use:

  • your provider authorize endpoint for direct-provider flows
  • your app login page for app-owned auth flows

Token Endpoint#

This is required for popup-based PKCE exchange.

Registration Endpoint#

Use this when your auth server supports Dynamic Client Registration.

Client ID#

Set this only when you are using a preregistered public client.

For the local Todo demo, the seeded example client is todo-local.

Resource#

Set this to the exact audience of the public MCP server URL.

For Gateway-backed OAuth flows, that means:

  • MCP clients authenticate to the Emcy Gateway URL
  • your downstream app keeps its own API audience
  • Emcy bridges those two token domains server-side

The local Todo demo validation flow now follows that Gateway model.

Registration preference#

Use:

  • auto to let Emcy choose
  • preregistered when you have a known public client
  • cimd when you want Emcy’s hosted client metadata identity
  • dcr when the auth server supports public PKCE DCR
  • manual only for exceptional cases

Production callback defaults#

The default Emcy popup callback is:

TEXT
https://emcy.ai/oauth/callback

If your docs or provider config still use https://emcy.ai/oauth/callback, update them.

Emcy’s hosted client metadata document is:

TEXT
https://emcy.ai/.well-known/oauth-client-metadata.json

Before you test#

Make sure all of these line up:

  • the server has an attached Gateway
  • the server Server URL is correct
  • the generated MCP server publishes protected-resource metadata
  • Resource matches the downstream API audience
  • for the current local Todo demo, Resource is http://localhost:5080/api/todos
  • your auth server allows https://emcy.ai/oauth/callback
  • the discovery inspector shows the capabilities you expect

Validation order#

Validate in this order:

  1. local preregistered Emcy agent flow
  2. public Emcy agent flow with CIMD
  3. public Emcy agent flow with DCR fallback
  4. VS Code against the same public MCP server
  5. embedded host-aware popup flow