Skip to main content

Pass user identity to MCP servers

MCP servers behind MintMCP sometimes need to know who is calling: to return user-specific data, enforce row-level access, or log the caller for audit purposes. MintMCP can forward the authenticated user's email address to upstream servers so they can make those decisions.

How the email reaches your server depends on the connector type:

Connector typeMechanismDefault
Remote MCPX-MintMCP-User-Email HTTP headerOff (opt-in per connector)
Hosted connector (stdio)MINTMCP_USER_EMAIL environment variableAlways on

Remote MCP servers​

For remote connectors, MintMCP injects an X-MintMCP-User-Email header into every proxied request when the connector admin enables it. The header contains the authenticated user's email address.

Because remote servers may be operated by third parties, this is off by default.

Enable the header​

  1. Open the connector's Connection settings
  2. Check Include user identity in requests to this server
  3. Save

Once enabled, your remote MCP server can read the header from incoming requests:

# Python (Flask / FastAPI)
user_email = request.headers.get("X-MintMCP-User-Email")
// Node.js (Express)
const userEmail = req.headers["x-mintmcp-user-email"];

Hosted connectors​

Hosted connectors run inside MintMCP's managed infrastructure for your organization.

For stdio-based MCPs, MintMCP automatically sets the MINTMCP_USER_EMAIL environment variable for every request from a user principal.

Read it like any other environment variable:

import os
user_email = os.environ.get("MINTMCP_USER_EMAIL")
const userEmail = process.env.MINTMCP_USER_EMAIL;

Agent identities​

When the caller is an agent identity rather than a person, MintMCP forwards the agent's configured identity email through the same mechanisms: the X-MintMCP-User-Email header for remote connectors (still opt-in per connector) and the MINTMCP_USER_EMAIL environment variable for hosted connectors.

Set the address in the Identity email field on the agent MCP's Credentials tab. New agents get a default derived from the agent's name at your organization's verified domain, and clearing the field means the agent forwards no identity.