Getting Started

Embed an agent in your app

Copy the agent embed snippet, set allowed origins, and use embedded popup auth with host-account hints.

6 sections2 locales

Once your agent is configured, embedding it in your app is straightforward:

  1. get an Emcy API key
  2. copy the agent embed snippet
  3. set allowed origins
  4. pass host identity into embeddedAuth
  5. test the same MCP server in both the agent playground and your embed

Embed always starts with an agent.

If one of that agent's attached MCP servers needs user-scoped OAuth, the embed will use that server's Gateway-backed path. If not, Gateway does not need to be in the way.

1. Get the values you need#

You need:

  • an API key from /api-keys
  • the agent ID, used as agentId

2. Start with the drop-in React widget#

TSX
import { EmcyChat } from "@emcy/agent-sdk/react";
 
function App() {
  return (
    <div className="h-[600px]">
      <EmcyChat
        apiKey="YOUR_API_KEY"
        agentId="YOUR_AGENT_ID"
        mode="inline"
        title="Support Agent"
        embeddedAuth={{
          hostIdentity: {
            subject: session?.user?.id,
            email: session?.user?.email,
            organizationId: session?.organizationId,
            displayName: session?.user?.name,
          },
          mismatchPolicy: "block_with_switch",
        }}
      />
    </div>
  );
}

Use:

  • mode="inline" for dashboards, admin panels, and in-product sidebars
  • the default floating mode for support-widget style chat

3. Set allowed origins before production#

Back in the agent Configuration tab, make sure Allowed Origins includes the domains where the embed will run.

Example:

TEXT
https://yourdomain.com, https://app.yourdomain.com

4. Use embedded popup auth, not host-delivered MCP tokens#

For embedded MCP auth:

  • pass embeddedAuth so Emcy knows who the current app user is
  • let Emcy own the popup callback and client metadata routes
  • let Emcy broker downstream grants server-side

That keeps the embed and agent products on the same OAuth structure while making the embed feel like it belongs to the signed-in host app.

5. Validate the same server in playground and embed#

Before shipping:

  1. open the agent Playground
  2. test the same MCP server there
  3. test the embedded widget in your app
  4. confirm both paths use the same Gateway-backed MCP deployment

For the local Todo demo, the expected behavior is:

  • agent popup auth works
  • the embedded widget starts from the current Todo account
  • the popup only stays interactive when silent same-account auth cannot finish

6. When to use the other embed options#

Use React Hook (Custom UI) when you want your own layout.

Use Vanilla JavaScript when you are not using React.