Embed an agent with app auth

Use @mcpstack/agent-sdk when you want an MCP Stack agent inside your own product. In an embedded app, the normal path is app-owned auth: your app keeps its existing session, the SDK asks your app for the current access token, and Gateway exchanges that app token for an MCP-facing token.

Secure request path#

Your app owns the user session. Gateway validates the app token and mints an MCP-facing token for tool calls.

Requirements#

Before you embed:

• a healthy MCP server with tools/list passing
• a Gateway profile attached when the server uses user-scoped auth
• an MCP Stack agent attached to that server
• an mcpstack_pk_* agent public key with allowed browser origins configured
• verified domain ownership for each production browser domain on the agent Embed tab
• a stable userIdentity and appSessionKey in your host app

Dashboard path#

1. Open Agents and create or select an agent.
2. Attach the MCP servers the agent should use.
3. Open the agent Embed tab.
4. Verify each production domain by adding the TXT record shown in the Verified domains card and confirming ownership. Localhost origins are auto-verified for development.
5. Create an embed key with exact allowed origins for your app.
6. Copy the public mcpstack_pk_* key. Public embed keys remain visible after creation.
7. Copy the SDK snippet for your stack.
8. Test in the agent playground before shipping to production.

Configure agent budgets on the agent Budget & Usage tab if you need spend limits.

React quick start#

Install the SDK:

npm install @mcpstack/agent-sdk

Render with app-token auth:

import { useAppAgent } from "@mcpstack/agent-sdk/react";
 
export function SupportAssistant({ session }: { session: AppSession }) {
  const agent = useAppAgent({
    apiKey: process.env.NEXT_PUBLIC_MCPSTACK_AGENT_API_KEY!,
    agentId: "ag_support",
    appSessionKey: session.id,
    userIdentity: {
      subject: session.user.id,
      email: session.user.email,
      displayName: session.user.name,
      organizationId: session.organizationId,
    },
    auth: {
      mode: "app-token",
      getToken: () => session.getAccessToken(),
    },
  });
 
  return <YourAssistantUi agent={agent} />;
}

CLI path#

Inspect embed-related agent configuration:

mcpstack agents get ag_support --json
mcpstack agents usage ag_support --json
mcpstack gateways logs gw_support

Use Gateway logs when exchange succeeds in the playground but fails in your app.

API path#

Read agent configuration:

GET /api/v1/organizations/{orgId}/agents/{agentId}
Authorization: Bearer {token}

Read agent usage summary:

GET /api/v1/organizations/{orgId}/agents/{agentId}/usage
Authorization: Bearer {token}

Set the agent pool and default user budget from your backend:

PATCH /api/v1/organizations/{orgId}/agents/{agentId}/budget
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "monthlyBudgetUsd": 10000,
  "defaultUserBudgetUsd": 5
}

Required concepts#

auth.getToken should resolve the current app token every time the SDK calls it. Do not close over an initial page-load token if your auth library can refresh in the background.

Budget identity#

Agent budgets use the same stable app identity that the SDK sends with chat. For React embeds, use a durable userIdentity.subject; for headless calls, keep any explicit externalUserId equal to that same app user id.

const externalUserId = account.id;
 
const agent = createAppAgent({
  apiKey: "mcpstack_pk_xxxx",
  agentId: "ag_support",
  appSessionKey: `${account.organizationId}:${externalUserId}:${session.id}`,
  userIdentity: {
    subject: externalUserId,
    email: account.email,
    displayName: account.name,
    organizationId: account.organizationId,
  },
  auth: {
    mode: "app-token",
    getToken: () => appAuth.getAccessToken(),
  },
});

Budget mutation is backend-only. Your server should use an mcpstack_sk_* service-account key to call PUT /api/v1/organizations/{orgId}/agents/{agentId}/external-users/{externalUserId}/budget; browser SDK tokens and public embed keys must never update budgets.

What happens#

When an attached MCP server needs auth:

• The SDK calls auth.getToken().
• Gateway validates the token issuer, signature, audience, origin, agent, resource, and scopes against the existing Gateway profile and the agent's allowed origins.
• Gateway mints a short-lived MCP-facing token for the agent SDK.
• The MCP server receives the same user-scoped upstream access it would receive from a normal OAuth grant.

External MCP clients still use OAuth discovery and authorization against the same Gateway URL. See OAuth and Gateway fundamentals.

Session boundaries#

const appSessionKey = `${organizationId}:${userId}:${authSessionId}`;

Change it when the user signs out, a different user signs in, the tenant changes, or you intentionally want a fresh agent auth boundary.

Headless usage#

import { createAppAgent } from "@mcpstack/agent-sdk/app";
 
const agent = createAppAgent({
  apiKey: "mcpstack_pk_xxxx",
  agentId: "ag_support",
  appSessionKey,
  userIdentity,
  auth: {
    mode: "app-token",
    getToken: () => appAuth.getAccessToken(),
  },
});
 
const response = await agent.sendMessage({
  text: "Find the latest ticket for Acme.",
});

Troubleshooting#

Quick answer#

For a signed-in product, use auth.mode = "app-token", pass getToken, and keep userIdentity.subject stable. Keep standard Gateway OAuth enabled for external MCP clients.