MCPSail

Getting Started

MCP OAuth in embedded mode

Use MCPSail-owned popup OAuth with host-account hints so embeds feel native to the signed-in app experience.

6 sections2 locales

Embedded mode means the agent runs inside your app, not inside the managed MCPSail agent UI.

Not every embed needs this flow.

This page applies when an agent includes one or more OAuth-backed MCP servers and MCPSail Gateway owns the popup auth edge for that server.

The recommended embedded pattern is now:

  1. your app passes the current signed-in user as userIdentity
  2. the widget starts popup auth through MCPSail-owned helper routes
  3. MCPSail attempts to connect the downstream MCP auth flow as that same user
  4. if the downstream provider resolves a different account, MCPSail blocks the mismatch and asks the user to choose

Use an agent embed like this:

TSX
<MCPSailChat
  apiKey="YOUR_API_KEY"
  agentId="YOUR_AGENT_ID"
  userIdentity={{
    subject: session?.user?.id,
    email: session?.user?.email,
    organizationId: session?.organizationId,
    displayName: session?.user?.name,
  }}
/>

Important behavior:

  • the host app does not hand MCP tokens to the SDK
  • MCPSail owns the popup callback and client metadata routes
  • the SDK can attempt same-account auth first when the downstream provider supports it
  • mismatched downstream accounts are blocked until the user explicitly chooses to continue

Required agent setup#

Before testing an embed, do this in MCPSail:

  1. add the OAuth-enabled MCP server to the agent
  2. open the agent Configuration tab
  3. set Allowed Origins to the domains where the embed will run
  4. save the agent

Without correct allowed origins, the widget can load but fail when the browser tries to use the agent from your site.

Consumer apps stay clean#

Embedded popup auth does not require the consumer app to:

  • host an OAuth callback page for MCP auth
  • host a client metadata document for MCP auth
  • manage downstream refresh tokens
  • receive MCPSail MCP tokens directly

By default the SDK uses MCPSail-owned helper routes. On localhost, those default to:

TEXT
http://localhost:3100/oauth/callback
http://localhost:3100/.well-known/oauth-client-metadata.json

Same-account behavior#

If your app provides a host identity and the attached Gateway is configured with downstream identity resolution, MCPSail compares:

  • subject first when both sides provide one
  • otherwise normalized email
  • plus organizationId when both sides provide one

If MCPSail cannot resolve a comparable downstream identity, same-account embedded auth fails closed instead of silently binding the wrong account.

Advanced override#

If you need to replace the built-in popup flow, provide onAuthRequired. Most embedded apps should not need this.