Skip to content
Nevent Help Center

Nevent AI multi-tenant model

Nevent uses a hierarchical tenant model. Nevent AI lets you switch tenants within a session and work with multiple organizations without restarting the connection.

Role-based access model

Section titled “Role-based access model”
RoleWhat it can see
SUPERADMINAll tenants in the system
OWNERTheir own tenant and all child tenants
ADMINOnly their own tenant

The role of the authenticated user (the JWT used at login) determines which tenants are accessible through nevent_list_tenants.

Basic multi-tenant workflow

Section titled “Basic multi-tenant workflow”
1. nevent_list_tenants    → list accessible tenants (returns tenant IDs)
2. nevent_switch_tenant   → set the active tenant for this session
3. nevent_reset_tenant    → restore the origin tenant (SUPERADMIN only)

Example conversation

Section titled “Example conversation”
User: "List the available tenants"
→ nevent_list_tenants returns [tenant-abc, tenant-xyz, tenant-def]

User: "Switch to tenant-xyz"
→ nevent_switch_tenant({ tenantId: "tenant-xyz" })
→ Response: { active_tenant_id: "tenant-xyz" }

User: "List the campaigns"
→ nevent_list_campaigns queries in the context of tenant-xyz

User: "Go back to the original tenant"
→ nevent_reset_tenant()
→ Response: { active_tenant_id: "tenant-abc" }

nevent_switch_tenant contract

Section titled “nevent_switch_tenant contract”

When you call nevent_switch_tenant:

  1. The MCP server calls the tenant-switch endpoint on the Nevent API with { tenantId }.
  2. The API validates that the JWT bearer has access to the destination tenant and returns a new access token scoped to the new tenant.
  3. The MCP server updates the JWT in DataClient (analytics) and PaidMediaClient (paid media) atomically.
  4. All in-memory caches (capabilities, segmentation criteria) are invalidated — subsequent calls will get fresh data from the new tenant context.
  5. activeTenantId is updated from the tenantId claim in the new JWT.

nevent_reset_tenant contract

Section titled “nevent_reset_tenant contract”

When you call nevent_reset_tenant:

  1. The server reads homeTenantId — the tenant ID captured from the original JWT when the session was created.
  2. It calls the tenant-switch endpoint with { tenantId: homeTenantId }.
  3. Same cache invalidation and JWT rotation as in nevent_switch_tenant.
  4. If homeTenantId is not available (the original JWT had no tenantId claim), the tool returns an error.

Isolation guarantees

Section titled “Isolation guarantees”
  • Session scope: the tenant context is per session. Switching tenants in one conversation does not affect any other active sessions from the same user or other users.
  • JWT atomicity: JWT rotation is atomic. If the API call fails, neither client (DataClient nor PaidMediaClient) is updated. The active tenant does not change on error.
  • Verifiable response: the response from nevent_switch_tenant includes active_tenant_id so the agent can verify the switch completed correctly before continuing.

Segment management tools in multi-tenant

Section titled “Segment management tools in multi-tenant”

Segment operations (nevent_list_segments, nevent_get_segment, nevent_create_segment, nevent_update_segment) always operate on the currently active tenant.

If you need to list the segments of a specific tenant:

1. nevent_switch_tenant({ tenantId: "tenant-xyz" })
2. nevent_list_segments  → lists segments for tenant-xyz
3. nevent_reset_tenant   → restores original tenant

nevent_help tool

Section titled “nevent_help tool”

If the agent has questions about the multi-tenant workflow, it can invoke:

nevent_help({ topic: "tenants" })

This tool provides in-session contextual guidance on workflows, errors and the multi-tenant model without needing to consult external documentation.

Next step

Section titled “Next step”