Anonymous and unauthenticated users

This page explains how ChatGPT (and similar MCP hosts) work with Agentsyx when the end user starts without a full Agentsyx / Clerk account, then moves to a real account—the mixed auth path—and what your MCP app and downstream server should expect.

For the wire format of params._meta and openai/subject, see Injected parameters & metadata. For HTTP headers on your MCP URL, see Inputs to downstream servers. For attaching the app in ChatGPT, see Register in ChatGPT (OpenAI).

ChatGPT path vs in-app embedding

ChatGPT / OAuth: The user signs in through OAuth to Agentsyx (per OpenAI’s connector flow). MCP tools/call requests can include params._meta["openai/subject"]: a stable anonymous id from the host that Agentsyx uses to key anonymous usage until (and after) the user upgrades.
In-app embedding: Some Agentsyx UIs call MCP through an internal HTTP proxy that attaches a session token. That is a different surface from ChatGPT’s OAuth + MCP metadata model; do not assume it is the only way identity reaches your tools.

Identifiers (glossary)

Concept	What it is
`openai/subject` (full anon id)	Opaque string carried in `params._meta["openai/subject"]` on `tools/call`. It is the host’s stable handle for that ChatGPT user/installation. Agentsyx maps it to anonymous plan, credits, and linking when the user creates a real account.
Short anon id	A short, stable correlate (typically six characters) derived from the full anon id. It appears in portal and sign-in URLs as the query parameter `N=`, so the browser flow can tie the new Clerk session to the same anonymous record.
`params.arguments`	The JSON object of tool inputs from the model (your schema). This is separate from metadata.
`params._meta`	Optional MCP metadata on `params` (sibling of `name` and `arguments`). Host- and platform-injected keys such as `openai/subject` live here—not inside `arguments`.

Mixed-auth lifecycle

Phase A — Anonymous plan (no real account yet)
The end user can use the MCP app within the limits of the anonymous subscription. From your perspective:

params._meta["openai/subject"] should usually be present for ChatGPT-originated calls; still code defensively if it is missing.
Your downstream MCP server may receive headers such as x-a6-is-anon-user, x-a6-short-anon-id, x-a6-anonymous-subscription, x-a6-portal-link, and x-a6-login-link when Agentsyx has that context (see the inputs reference).

Treat this as “free / no durable human identity” for product purposes: you may limit features, cap storage, or require sign-in for sensitive actions—even though upstream billing and credits are still enforced by Agentsyx.

Phase B — Upgrade (portal / sign-in)
When the user should create or link a real account, the MCP App (widget) or tool responses can steer them to the portal or sign-in URL Agentsyx provides. Those URLs include ?N=<shortId> so that, after Clerk sign-up or sign-in, Agentsyx can associate the existing anonymous record with the new authenticated user.

Phase C — Account created
Once the user has a Clerk account with Agentsyx, they are no longer on the anonymous plan for that linkage. Subscription and billing context follow the real user.

Phase D — Merge in Agentsyx
Agentsyx merges the prior anonymous user row into the authenticated user: it records the relationship between the Clerk-backed user and the old anon id / short id, stores which previous user UUID was merged, and retires anonymous-only rows and related resources according to platform rules. You should not depend on internal table names—only on the identifiers and headers documented here.

Phase E — Calls after merge
Subsequent tools/call traffic may include x-a6-user-uuid, x-a6-username, x-a6-email, and x-a6-merged-user-uuid (comma-separated UUIDs of former user records, such as anonymous rows, that Agentsyx merged into the current user).

Your downstream MCP server is responsible when x-a6-merged-user-uuid appears: merge any user-scoped data you store from those old UUIDs into the canonical user, keep a record of merges you have applied, and make the operation idempotent so duplicate or repeated headers do not corrupt data. Agentsyx does not modify your server’s datastore for you. Details: Inputs to downstream servers.

Two user shapes (what to implement in your app)

Anonymous shape — Durable key: openai/subject in params._meta, and/or x-a6-short-anon-id if you only read headers. Do not assume email or real name exists.
Authenticated shape — Stable key: platform user identity (exposed via x-a6-* identity headers when present). After merge, x-a6-merged-user-uuid lists prior UUIDs your downstream MCP server must reconcile into that canonical user.

Downstream obligation: When x-a6-merged-user-uuid is provided, the downstream MCP server must perform the data merge, track which merges were applied, and keep merge handling idempotent. See Inputs to downstream servers.

Edge case: A new Clerk account is created when the anonymous side already had a user UUID in Agentsyx. The platform merge path connects those identities; your downstream server still reconciles stored state when x-a6-merged-user-uuid appears, not only when openai/subject changes.

Flow overview (ChatGPT → upgrade → merge)

sequenceDiagram
  participant Host as ChatGPT
  participant Platform as Agentsyx
  participant Downstream as YourMCP
  participant User as EndUser
 
  Host->>Platform: tools/call with params._meta openai/subject
  Platform->>Downstream: JSON-RPC plus optional x-a6 anon headers
  Note over Downstream: Limited features or errors with portal hint
  User->>Platform: Open portal or sign-in with N=shortId
  User->>Platform: Complete Clerk sign-up or sign-in
  Platform->>Platform: Merge anonymous profile into authenticated user
  Host->>Platform: Later tools/call
  Platform->>Downstream: JSON-RPC plus identity and x-a6-merged-user-uuid when applicable

Practical guidance

Treat openai/subject as optional in code paths where the host might omit _meta; default to safe, non-destructive behavior.
Do not re-implement subscription or credit enforcement in place of Agentsyx; still gate expensive side effects in your own tools if needed.
Rate-limit high-cost operations if anonymous users can trigger them.

For injection details, see Injected parameters & metadata.

Injected parameters & metadata MCP server metadata