Getting Started

MCP OAuth in embedded mode

Use Emcy-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 Emcy agent UI.

Not every embed needs this flow.

This page applies when an agent includes one or more OAuth-backed MCP servers and Emcy 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 embeddedAuth.hostIdentity
  2. the widget starts popup auth through Emcy-owned helper routes
  3. Emcy attempts to connect the downstream MCP auth flow as that same user
  4. if the downstream provider resolves a different account, Emcy blocks the mismatch and asks the user to choose

Use an agent embed like this:

TSX
<EmcyChat
  apiKey="YOUR_API_KEY"
  agentId="YOUR_AGENT_ID"
  embeddedAuth={{
    hostIdentity: {
      subject: session?.user?.id,
      email: session?.user?.email,
      organizationId: session?.organizationId,
      displayName: session?.user?.name,
    },
    mismatchPolicy: "block_with_switch",
  }}
/>

Important behavior:

  • the host app does not hand MCP tokens to the SDK
  • Emcy 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 Emcy:

  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 Emcy MCP tokens directly

By default the SDK uses Emcy-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, Emcy compares:

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

If Emcy 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.