Getting Started

MCP OAuth in agent mode (popup)

Understand how the Emcy agent UI handles OAuth popups, what needs to be configured first, and how to verify that a server is connected.

8 sections2 locales

Agent mode is the Emcy-managed validation path. It is the easiest place to validate a Gateway-backed OAuth flow before you test external clients or embedded apps.

What needs to be true first#

Before popup auth can work, make sure:

  1. the MCP server uses OAuth 2.0
  2. the server is attached to the agent
  3. the runtime Server URL is reachable
  4. Resource matches the MCP server audience
  5. the discovery inspector shows the expected auth metadata

For popup-based exchange, also make sure the auth config has the right authorize and token endpoints.

Default callback#

The default Emcy popup callback is:

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

If your auth server allowlist still points at https://emcy.ai/oauth/callback, update it.

How the flow works#

MERMAID
flowchart LR
    A["Agent Playground"] --> B["Server shows Needs Auth"]
    B --> C["User clicks Sign In"]
    C --> D["Popup opens with PKCE"]
    D --> E["Auth server login completes"]
    E --> F["Emcy callback resolves token"]
    F --> G["Server status becomes Connected"]

What Emcy resolves for you#

In agent mode, Emcy handles:

  • protected-resource and auth-server discovery
  • registration mode selection
  • popup launch and callback handling
  • token storage and refresh
  • resource-aware token reuse

That makes agent mode the right place to validate the Todo sample app first.

Suggested validation path#

  1. Attach the Todo MCP server to an agent.
  2. Open Playground.
  3. Trigger a protected tool call.
  4. Confirm the server shows Needs Auth.
  5. Complete the popup flow.
  6. Confirm the server shows Connected.
  7. Retry the tool call and verify user-scoped Todo data is returned.

Expected modes#

Depending on the auth server metadata, the effective registration mode should be one of:

  • preregistered for local seeded client validation
  • cimd for Emcy’s Gateway-managed public client identity
  • dcr for public PKCE DCR fallback

If the inspector or runtime falls back to manual unexpectedly, your metadata is incomplete.

Common failure modes#

  • wrong Resource value: auth succeeds but tool execution fails with audience errors
  • missing registration_endpoint: DCR clients cannot register
  • missing client_id_metadata_document_supported: Emcy cannot use CIMD
  • callback allowlist drift: login succeeds at the provider but the popup cannot finish
  • wrong Server URL: auth completes but the agent cannot call the MCP server