Security and identity model

MCP Stack is designed so production agents do not need shared service-account shortcuts for user data. The preferred model is:

• The user signs in to the downstream app or authorization server.
• For an embedded app, the SDK asks the app for the current user token and Gateway validates it.
• For an external MCP client, Gateway brokers and stores the downstream OAuth grant.
• The MCP client or embedded agent receives an MCP-facing token.
• The runtime receives only the access it needs to call the upstream API.
• Logs and usage can be attributed to users, agents, servers, and tools.

Gateway brokers the user grant and keeps the OAuth boundary out of every individual MCP client.

Embedded app auth#

Use app-token auth when the agent is embedded inside a product that already signed the user in.

useAppAgent({
  apiKey: "mcpstack_pk_xxxx",
  agentId: "ag_xxxxx",
  appSessionKey: session.id,
  userIdentity: {
    subject: session.user.id,
    email: session.user.email,
    organizationId: session.organizationId,
  },
  auth: {
    mode: "app-token",
    getToken: () => session.getAccessToken(),
  },
});

Gateway accepts that token only when the MCP server's Gateway profile matches the token issuer and audience, the agent is linked to that server, the request origin is allowed for the agent, and the requested scopes fit the server. The app remains responsible for issuing and refreshing its own user token.

The token getter should read from the app's current session at call time. If the app refreshes tokens, the SDK should receive the refreshed token without requiring a page reload or a second sign-in flow.

External OAuth clients#

Use Gateway OAuth when an external MCP client needs user-scoped access to an upstream API.

Gateway needs:

• Authorization server issuer or metadata URL.
• Registered client ID.
• Resource or audience.
• Scopes.
• Callback URL registered with the downstream provider.

Gateway publishes OAuth protected-resource and authorization-server metadata so MCP clients can discover how to authorize.

Embedded app auth and external OAuth can coexist on the same Gateway-backed MCP server.

Same user, different sessions#

Gateway can see the same person through more than one path:

• Embedded app: the SDK exchanges the app's current user token.
• External client: ChatGPT, Claude, Cursor, or another client completes OAuth.

If both paths authenticate the same app user in the same organization, Gateway should treat them as the same user for tool permissions and audit identity.

Use the stable app user id and organization/workspace id for that match. A session id is useful for debugging which login or grant was used, but it should not be the only value that decides who the user is.

Static headers#

Use Static Headers when every tool call should include the same upstream value.

Examples:

• X-API-Key=UPSTREAM_API_KEY
• X-Tenant-Id=UPSTREAM_TENANT_ID
• Authorization=UPSTREAM_AUTHORIZATION

Static headers are not the right answer for user-scoped OAuth. If a token should vary by user, use Gateway.

Public API mode#

Use Public API mode when no upstream credentials are required by the generated runtime.

Examples:

• Public data APIs.
• Demo APIs.
• Internal APIs behind a trusted network where auth is already handled outside the runtime.

Public API mode does not add an OAuth layer.

Embedded user identity#

When using @mcpstack/agent-sdk, pass the current host-app user as userIdentity:

<McpStackChat
  apiKey="mcpstack_pk_xxxx"
  agentId="ag_xxxxx"
  appSessionKey={session.id}
  userIdentity={{
    subject: session.user.id,
    email: session.user.email,
    organizationId: session.organizationId,
    displayName: session.user.name,
  }}
/>

This tells the SDK which signed-in user is using the agent. With app-token auth, it also gives Gateway and usage analytics a stable user and organization boundary.

App session boundaries#

Pass appSessionKey from your host app session. This prevents persisted MCP auth and resumed conversations from leaking across logout/login boundaries.

Use a value that changes when:

• The user signs out.
• A different user signs in on the same browser.
• The tenant or organization context changes.

Do not use a static value for every user.

Service-account API keys#

MCP Stack service-account keys are for automation against MCP Stack management APIs and CLI workflows. They are not a replacement for downstream user OAuth.

Use service-account keys for:

• CI.
• Server lifecycle automation.
• Listing servers or agents.
• Running smoke checks.

Do not use service-account keys to impersonate end users inside a SaaS product.

Client tools#

clientTools run inside the host app, not on the MCP server. They let an embedded agent manipulate local UI state, read page context, draft form fields, or trigger host-app workflows.

Treat client tools as privileged app code:

• Keep names and descriptions clear.
• Make risky tools explicit.
• Require confirmation for destructive actions.
• Avoid returning secrets or unnecessary page data.
• Prefer server MCP tools for authoritative backend writes.

Quick answer#

Choose the auth mode that matches your upstream API:

• Public or already-open upstream API: Public API.
• Same fixed API key for every call: Static Headers.
• User-specific access, OAuth, OIDC, or bearer-protected API: Gateway.
• CI against MCP Stack management APIs: service-account API key.
• Embedded user identity in a product: userIdentity, appSessionKey, and auth.getToken.

Organization roles and billing#

Member roles (Owner, Admin, Developer, Viewer) control what each person can do in your organization. Billing visibility and checkout are separate from general read-only access.

See Organization roles and billing access for the full role and billing matrix.

See also API keys and service accounts for automation credentials and Embed an agent with app auth for end-user identity in embedded surfaces.