Agent Session Parameters

When a Mindset AI agent calls an MCP tool on behalf of a user, the tool needs to know who is making the request. Which user is asking? What are they allowed to see? Should they have admin access or regular access? Agent Session Parameters answer these questions. They are HTTP headers that the Mindset AI platform attaches to every MCP tool request, carrying user identity and session context from the client application through to your MCP server. Your server uses these headers to scope data access, enforce permissions, and implement role-based authorization.

Why this matters

Without identity context, an MCP tool has no way to distinguish one user from another. Every request looks the same. This means either everyone sees everything (a security problem) or the tool has to ask the LLM for user identification (unreliable and gameable). Agent Session Parameters solve this by establishing identity at the infrastructure level, outside the LLM’s control. The user’s identity comes from authenticated session data, not from what the LLM decides to pass. The LLM never sees these headers and cannot tamper with them. This is especially important for:

Multi-tenant applications. Your MCP server needs to return only data that belongs to the requesting user’s organization, not data from other tenants.
Role-based access. A regular user asking “show me my reviews” should see their own reviews. A manager asking “show me my team’s reviews” should see their direct reports’. An admin should see everyone’s.
Audit trails. Knowing which user triggered which tool call is essential for compliance and debugging. The headers provide this without relying on the LLM to report it accurately.
Data minimization. Your MCP server can filter results at the source, returning only what the user is entitled to see, before the data ever reaches the LLM.

The headers your MCP server receives

Every MCP tool request from the Mindset AI platform includes these HTTP headers:

Header	Source	Purpose
`x-user-id`	`externalUserId` from the AgentSessions API	Identifies the end user in your system. Use this to scope data access.
`x-app-uid`	Platform-provided	Internal Mindset AI application identifier. Available for logging and correlation.
`x-session-tags`	`tags` from the AgentSessions API (JSON array)	Arbitrary strings for filtering, segmentation, or access control. You define the meaning.
`x-human-uid`	Platform-provided	Internal Mindset AI user identifier. Use for logging and correlation only, not for authorization.

These headers are set by the platform based on authenticated session data. They are not generated by the LLM and cannot be influenced by user messages or prompt injection.

How session parameters are established

Session parameters are set once, when the client application creates an agent session via the AgentSessions API, before any conversation happens.

{
  "agentUid": "your-agent-uid",
  "externalUserId": "emp-4821",
  "tags": ["department:engineering", "role:manager", "region:emea"],
  "contextUids": ["knowledge-base-1", "knowledge-base-2"],
  "mcpserverUids": ["mcp-server-hr", "mcp-server-crm"]
}

Field	What it does
`externalUserId`	Becomes the `x-user-id` header on every MCP request. This is your user’s identifier in your own system.
`tags` (max 10)	Becomes the `x-session-tags` header (JSON array). Use for any classification, filtering, or access control logic your MCP server needs.
`contextUids` (max 30)	Scopes which knowledge bases the agent can search. Not sent to MCP servers.
`mcpserverUids` (max 5)	Scopes which MCP servers the agent can call. Not sent to MCP servers.

The structural fields (contextUids, mcpserverUids) configure the agent’s capabilities for the session. The identity fields (externalUserId, tags) travel with every tool request as headers.

How session parameters compare to other data channels

Agent Session Parameters are one of four channels for passing data from the client to the agent system:

	Agent Session Parameters	Situational Awareness	Pass-through Parameters
Purpose	Identity, routing, and authorization	Give the agent context to reason about	Give tools exact data without LLM involvement
When set	Once, at session creation	Per message	Per message
Who sees it	MCP servers only (as HTTP headers)	The LLM (in its system prompt)	The MCP server only
LLM sees it?	No, by design	Yes, that’s the point	No, by design
Typical content	User ID, session tags	Page title, user role, priming question	JSON payloads, document content

The boundaries are clean: identity goes through session parameters, reasoning context goes through Situational Awareness, and bulk data goes through Pass-through Parameters. They do not overlap. See Data channels overview for the full four-channels picture, including Page Tools.

Implementation guide

Reading headers in your MCP server

Every MCP tool request arrives with the identity headers. How you access them depends on your framework. Python (FastMCP):

from fastmcp.server.dependencies import get_http_headers

@mcp.tool()
async def get_my_records() -> dict:
    """Get records for the current user."""
    headers = get_http_headers()
    user_id = headers.get('x-user-id')
    app_uid = headers.get('x-app-uid')
    session_tags = json.loads(headers.get('x-session-tags', '[]'))

    records = fetch_records_for_user(user_id)
    return {
        "status": "success",
        "message": f"Found {len(records)} records",
        "data": {"records": records}
    }

TypeScript (MCP SDK):

server.tool('get_my_records', {}, async (params, extra) => {
  const headers = extra.requestContext?.headers ?? {};
  const userId = headers['x-user-id'];
  const appUid = headers['x-app-uid'];
  const sessionTags = JSON.parse(headers['x-session-tags'] ?? '[]');

  const records = await fetchRecordsForUser(userId);
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        status: 'success',
        message: `Found ${records.length} records`,
        data: { records },
      }),
    }],
  };
});

Who is the user? Headers vs parameters

Most tools act on behalf of the requesting user: “show me my records”, “update my settings”, “search my documents.” For these, the user’s identity comes from the x-user-id header. The tool does not need a user ID parameter because the platform already knows who is asking.

@mcp.tool()
async def get_my_profile() -> dict:
    """Get the current user's profile."""
    headers = get_http_headers()
    user_id = headers.get('x-user-id')  # Platform provides identity
    return fetch_profile(user_id)

Some tools are admin operations that act on a different user: “reset this employee’s password”, “view this team member’s records.” These need two identifiers: the person performing the action (from the header) and the person being acted on (from a parameter). The header is used for the authorization check; the parameter identifies the target.

@mcp.tool()
async def reset_user_password(target_user_id: str) -> dict:
    """Admin tool: reset a user's password."""
    headers = get_http_headers()
    admin_id = headers.get('x-user-id')  # Who is performing the action

    if not is_admin(admin_id):
        return {
            "status": "error",
            "message": "This action requires admin permissions",
            "data": None
        }

    result = perform_password_reset(target_user_id)  # Who is being acted on
    return {
        "status": "success",
        "message": "Password reset successfully",
        "data": result
    }

The principle in both cases: x-user-id is the trusted identity of the person making the request. It comes from authenticated session data that the LLM cannot influence. Use it for authorization decisions. When a tool needs to reference a different user (admin scenarios), accept that as a parameter but always verify that the requester has permission first.

Using session tags for entitlement filtering

Session tags are arbitrary strings that you define. The Mindset AI platform passes them through without interpreting them. This gives you a flexible mechanism for access control, segmentation, and filtering. Setting tags at session creation:

{
  "externalUserId": "emp-4821",
  "tags": ["department:engineering", "role:manager", "clearance:confidential"]
}

Reading tags in your MCP server:

@mcp.tool()
async def search_documents(query: str) -> dict:
    """Search documents the current user has access to."""
    headers = get_http_headers()
    user_id = headers.get('x-user-id')
    tags = json.loads(headers.get('x-session-tags', '[]'))

    # Parse tag key-value pairs
    tag_map = {}
    for tag in tags:
        if ':' in tag:
            key, value = tag.split(':', 1)
            tag_map[key] = value

    department = tag_map.get('department')
    clearance = tag_map.get('clearance')

    # Scope the search to what this user can access
    results = search_with_filters(
        query=query,
        department_filter=department,
        clearance_level=clearance,
    )

    return {
        "status": "success",
        "message": f"Found {len(results)} documents",
        "data": {"documents": results}
    }

Common tag patterns:

Pattern	Example tags	Use case
Department scoping	`department:engineering`, `department:sales`	Filter data to the user’s department
Role-based access	`role:viewer`, `role:editor`, `role:admin`	Gate write operations
Region filtering	`region:emea`, `region:apac`	Return region-appropriate data
Feature flags	`feature:beta-reports`, `feature:advanced-search`	Enable functionality per session
Tenant isolation	`tenant:acme-corp`	Multi-tenant data separation

Tags are strings with no enforced structure. The key:value convention shown above is a recommendation, not a requirement. Your MCP server defines what tags mean and how to interpret them.

Security considerations

Your MCP server is the authorization boundary

The Mindset AI platform authenticates the request (validates the API key, attaches identity headers) but does not authorize it. Authorization is your MCP server’s responsibility. The platform tells you who the user is; you decide what they can see and do. This means:

Filter data at the source. Do not return all records and rely on the LLM to filter. The LLM sees everything you return and might choose to reveal it to the user.
Validate permissions before acting. Check x-user-id and x-session-tags before performing write operations.
Return only what is needed. Follow the principle of least privilege. If the user asked about their own profile, return their profile, not everyone’s.

What the LLM sees

The LLM sees the tool’s response in full. Whatever your MCP server returns becomes part of the LLM’s context, and the LLM may surface any of it in conversation. If there is information you never want a user to see, do not make it available to the LLM. This applies to MCP server responses, tool outputs, and any other data that enters the agent’s context. LLMs are not reliable keepers of secrets. This is not a prohibition on returning sensitive data. If your use case requires it, that is your decision. But make it a conscious one, with an understanding of where that data ends up.

Header trust model

The x-user-id, x-app-uid, and x-session-tags headers are set by the Mindset AI platform based on authenticated session data. They are trustworthy as long as:

Your MCP server validates the API key (Bearer token) via the authentication middleware. This confirms the request came from the Mindset AI platform, not from an arbitrary caller.
You do not expose your MCP server endpoint publicly without API key validation.

If someone bypasses the API key check, they can set any headers they want. The API key is what makes the headers trustworthy.

Quick reference

Concept	Description
`x-user-id`	Current user’s external ID (from `externalUserId` at session creation)
`x-app-uid`	Internal Mindset AI application identifier (logging only)
`x-session-tags`	JSON array of session tags (from `tags` at session creation)
`x-human-uid`	Internal Mindset AI user ID (logging only)
AgentSessions API	Where session parameters are set (once, before conversation)
Regular tools	Use `x-user-id` for identity; never accept user ID as a parameter
Admin tools	Use `x-user-id` to verify admin status; accept target user as a parameter

Data channels overview

The four channels in context, including how session parameters relate to the others.

Situational Awareness

Per-message context for the LLM.

Pass-through Parameters

Direct data injection into tool calls.

AgentSessions API

How to create sessions with parameters.

Overview

Integrate Agent Chat SDK 3

Agent Chat SDK 3: Client-side Integration APIs

Data channels

Integrate Agent Chat SDK 2

MCP Server Integration

Agent Builder SDK Integration

API Overview

API playground

Webhooks

Why this matters

The headers your MCP server receives

How session parameters are established

How session parameters compare to other data channels

Implementation guide

Reading headers in your MCP server

Who is the user? Headers vs parameters

Using session tags for entitlement filtering

Security considerations

Your MCP server is the authorization boundary

What the LLM sees

Header trust model

Quick reference

Data channels overview

Situational Awareness

Pass-through Parameters

AgentSessions API

​Why this matters

​The headers your MCP server receives

​How session parameters are established

​How session parameters compare to other data channels

​Implementation guide

​Reading headers in your MCP server

​Who is the user? Headers vs parameters

​Using session tags for entitlement filtering

​Security considerations

​Your MCP server is the authorization boundary

​What the LLM sees

​Header trust model

​Quick reference

​Related

Data channels overview

Situational Awareness

Pass-through Parameters

AgentSessions API

Why this matters

The headers your MCP server receives

How session parameters are established

How session parameters compare to other data channels

Implementation guide

Reading headers in your MCP server

Who is the user? Headers vs parameters

Using session tags for entitlement filtering

Security considerations

Your MCP server is the authorization boundary

What the LLM sees

Header trust model

Quick reference

Related