How to initialize per-participant / per-user MCP server in LiveKit Agents (Python)

Getting Started
1

I’m building a voice agent with the LiveKit Agents Python SDK. My MCP server returns different data per user (e.g. per-user auth or tenant), so I need the agent to use one MCP configuration per participant/session, not a single global one.

Current setup:

  • Agent entrypoint runs per job (when the agent is dispatched to a room).

  • I get user/session context via job metadata when dispatching (e.g. {"AUTH_KEY": "..."}).

  • I’d like to use that metadata to build the MCP client (e.g. MCPServerHTTP with per-user Authorization header) so that each participant’s session uses their own AUTH_KEY and thus their own data from the MCP server.

What I need:

  • The recommended way in agent.py to initialize MCP per participant (or per job): e.g. reading auth/session info from JobContext / job metadata and passing it into the agent (or AgentSession) so that each connected user gets their own MCP tools/context.

  • Any best practices or examples for per-user MCP configuration with LiveKit Agents Python (e.g. where to create MCPServerHTTP, how to pass job metadata into the agent constructor, and whether the same pattern works for both dev and production).

Relevant snippet (conceptual):

  • Dispatch sends metadata like: {"AUTH_KEY": "user_specific_token"}.

  • In the agent entrypoint I have access to ctx: JobContext and ctx.job.metadata.

  • I need to turn that into an MCP config (e.g. headers) and use it only for that job/session, so each participant’s session talks to the MCP server with their own credentials.

Could you point me to the right place in agent.py to do this initialization (e.g. in the entrypoint before session.start(), or via a custom agent class that receives per-job config), and any example or doc that shows per-participant/per-job MCP setup?

Thanks in advance.

2

Yes. I’d initialize it in the job entrypoint, before session.start(). Read ctx.job.metadata, extract the per-user token, then construct mcp.MCPServerHTTP(…, headers={…}) and pass it into AgentSession(mcp_servers=[…]). That gives you per-job/per-session MCP config, which is the right pattern when one dispatched job corresponds to one user session. If you have multiple users with different creds inside the same job/session, MCP config becomes session-scoped, so you may need separate jobs or a custom tool/auth layer instead.

1 Like