MCPSail

Getting Started

Add OAuth to your MCP server

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

8 sections2 locales

This page is about MCP client authentication: how MCPSail, 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 MCPSail, separate these concerns:

  • Authorization server: issues tokens
  • Protected resource: your MCP server
  • MCP client: MCPSail 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 MCPSail Gateway URL
  • your downstream app keeps its own API audience
  • MCPSail bridges those two token domains server-side

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

ChatGPT developer mode#

For ChatGPT's custom MCP connector form, open the server's Connect tab and use the ChatGPT developer mode card.

Use:

  • MCP Server URL: the connector URL
  • Protected resource metadata URL: the protected resource metadata field
  • Authorization server base: the authorization server base field
  • Auth URL: the auth URL field
  • Token URL: the token URL field
  • Registration URL: the registration URL field, if present
  • Resource: the resource field
  • Default scopes / base scopes: paste the listed Gateway scopes when ChatGPT asks for default or base scopes

If ChatGPT reports that DCR or CIMD is unavailable, use User-Defined OAuth Client and paste the endpoint values manually. Do not assume DCR or CIMD is available until the live MCP URL's discovery metadata advertises it.

Registration preference#

Use:

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

Production callback defaults#

The default MCPSail popup callback is:

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

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

MCPSail’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 MCPSail agent flow
  2. public MCPSail agent flow
  3. ChatGPT developer mode with the values from the Connect tab
  4. VS Code against the same public MCP server
  5. embedded host-aware popup flow