MCP 工具拿不到 user_id？用 contextvars 做请求级用户隔离

Ticnix
1 阅读17分钟

MCP 工具拿不到 user_id？用 contextvars 做请求级用户隔离

「AI Agent 工程化实战」系列 · 03

项目背景：广州气象大数据 + AI 智能体出行推荐系统（FastAPI + LangGraph + MCP + pgvector）

本文引用了 Python 官方文档、PEP 567 与 MCP 官方文档原文，链接见文末「参考资料」

0. 先用三句话讲清楚这篇在说什么

  1. 要解决的问题：Agent 调用某个工具时，工具需要知道"当前是哪个用户"，可这个身份只在 HTTP 请求最开头出现过，往后每一层（路由 → 鉴权 → Agent 图 → 工具）都没有它。
  2. 采用的方案：用 Python 标准库的 contextvars.ContextVar，在请求入口把 user_id "塞进"当前异步上下文，工具内部直接读出来——不用改任何工具的签名。
  3. 它的边界：contextvars 只在**同一个异步任务（Task）**里有效。跨线程要手动带过去，跨进程（比如独立运行的 MCP Server）完全读不到。正是这条边界，决定了"哪些工具能走 MCP、哪些必须留在本地"。

如果你只想记一句话：

contextvars 是"给每个异步任务发一个背包"，请求开始时把身份放进背包，调用链深处随时能掏出来；但它只在自己的任务里有效，出了任务就得显式搬运。

目录

  1. 从一个真实需求说起
  2. 先讲清三个概念（否则代码看不懂）
  3. 反面教材：三条走不通的路
  4. contextvars 到底是什么
  5. 项目落地：一条链路上的五根接力棒
  6. 边界：什么时候它会"失效"
  7. 为什么这套做法在业界很常见
  8. 小结与下一篇

一、从一个真实需求说起

用户在对话框里输入：

我上次收藏的那家餐厅叫什么来着？

这句话会触发一个私有工具 search_my_plans，去这个用户的私有知识库里检索。工具内部最后要执行一条 SQL：

SELECT ... FROM user_knowledge
WHERE user_id = :user_id AND embedding IS NOT NULL
ORDER BY embedding <=> :query_vec LIMIT 5

问题就出在 :user_id 上。这个值从哪来？

它最早出现在请求头里的 JWT token 里。然后要经过这么多层：

HTTP 请求（带 JWT）
  → FastAPI 路由函数
    → 鉴权依赖（解析 token 得到 user_id）
      → agent.chat(user_id=...)
        → LangGraph 图节点
          → ToolNode 执行工具
            → search_my_plans 内部

每一层都得把这个值带着走。而工具这一层，恰恰是最"深"、最不该关心上层结构的一层。

所以我们面对的核心问题是：

怎么把一个"只在请求开头存在"的值，送到"调用栈最深处"去使用，同时保证高并发下不会串号？

别急，在写代码之前，先把三个概念掰开讲清楚。这三个概念不搞懂，后面所有代码都只是"抄"。

二、先讲清三个概念

2.1 概念一：什么是"请求级上下文"

一个 Web 服务同时在处理很多请求。有些值天生属于"某一个请求"，而不是"整个进程"：

  • 当前用户是谁（user_id）
  • 这次请求的链路追踪 ID（trace_id）
  • 当前语言、时区、权限
  • 当前数据库事务/会话

这些值的共同点是：值本身随请求变化，但使用它的代码（工具、日志、DAO）位置固定、且很深层。

如果每个函数都加一个 user_id 参数来解决，那函数签名会膨胀得没法看，而且像日志这种"顺手打一行"的地方根本没法加参数。所以业界需要一个机制：让这些值"挂"在当前请求上，谁需要谁自己取。

2.2 概念二：为什么"全局变量"和 threading.local 都不行

先说全局变量。它在单线程、单请求的脚本里工作得很好：

CURRENT_USER = None   # 全局变量

def search_my_plans():
    return query(CURRENT_USER)

但一旦并发，就出事。原因在于异步（async）的本质：协程会在 await 处把控制权交出去，让别的协程先跑。看这张图：

sequenceDiagram
  participant A as 请求 A（用户 1）
  participant G as 全局变量 CURRENT_USER
  participant B as 请求 B（用户 2）

  A->>G: CURRENT_USER = 1
  B->>G: CURRENT_USER = 2
  Note over A,B: 两个请求在 await 处交错执行
  A->>G: 读取 CURRENT_USER
  G-->>A: 返回 2 ❌ 串号了

请求 A 明明只想查自己的资料，却读到了请求 B 的用户 ID。这就是数据越权，在真实系统里属于严重事故。

那用 threading.local 行不行？也不行。很多人对它有误解，以为它能救场：

threading.local 是按操作系统线程隔离的。而 asyncio 是单线程多协程——一个线程上跑着成百上千个协程。于是在这个线程里，所有协程共享同一份 threading.local 数据。PEP 567 的原文说得很直白：

Thread-local variables are insufficient for asynchronous tasks that execute concurrently in the same OS thread. Any context manager that saves and restores a context value using threading.local() will have its context values bleed to other code unexpectedly when used in async/await code. —— PEP 567 – Rationale

翻译过来：线程局部变量对付不了"同一线程里并发跑的异步任务"，值会意外地渗透到别的代码。 一句话，线程粒度太粗，不是我们需要的隔离粒度。

2.3 概念三：为什么 MCP 工具天生拿不到身份

这就要说到 MCP 协议的设计了。MCP 官方文档里有一句话，是整个取舍的根：

MCP is a stateless protocol. Every request carries the protocol version and the capabilities relevant to that request in its _meta field, so the server can process each request on its own. —— MCP 官方文档 · Architecture overview

MCP 被设计成无状态协议：每个请求自带它需要的信息，服务器独立处理每一个请求，不依赖"上一次你是谁"。这带来巨大的好处——服务器可以随便重启、扩容、被多个客户端共用。代价就是：它不会自动知道"当前用户是谁"，协议里也没有这个位置。

再加上本项目本地开发用的是 stdio 传输——MCP Server 是一个独立子进程：

Local MCP servers that use the STDIO transport typically serve a single MCP client... —— 同上

进程和进程之间的内存是不通的。 所以无论我们在 Agent 进程里怎么设置上下文，MCP 子进程都读不到。这就是第一个博客里那句结论的由来：有用户态的工具不能走 MCP。

到这里，三个概念齐了：

概念一句话
请求级上下文属于"某个请求"、需要被深层代码读取的值
为什么不用全局变量/thread-local并发会串号；thread-local 隔离粒度是"线程"，不是"任务"
为什么 MCP 拿不到身份MCP 协议无状态 + 子进程不共享内存

三、反面教材：三条走不通的路

把三条"想当然"的方案摆出来，你就能理解为什么最终选了 contextvars。

路线 1：全局变量

CURRENT_USER = None           # 模块级全局

def set_user(uid): 
    global CURRENT_USER
    CURRENT_USER = uid

@tool
def search_my_plans(query: str):
    ... WHERE user_id = CURRENT_USER   # 并发下读到别人的 id

失败原因：并发交错，值互相覆盖（见 2.2 的时间线图）。

路线 2：一路传参（显式参数）

async def search_my_plans(query: str, user_id: int):  # 把 user_id 加进签名
    ...

看起来"显式"很安全，但在这个项目里走不通，有两个硬伤：

  1. 工具签名是由 MCP 协议暴露的。你去改工具签名，等于改协议契约；而工具可能是独立服务，改一次要协调两边发版。
  2. 底层代码根本插不进去。比如日志、埋点、Agent 图节点里的中间件，这些地方并不适合逐个加参数。

路线 2 在"只有两三层"的小程序里是好方案，但当调用链很深、或工具是外部服务时，它会让参数渗透到每一个角落（业界叫"参数污染"）。

路线 3：threading.local

import threading
_current = threading.local()

def search_my_plans(query: str):
    uid = getattr(_current, "user_id", None)   # 异步下所有协程共享，等于没用

失败原因：asyncio 单线程跑多协程，threading.local 在这个线程里是"共用的"，起不到隔离作用（见 2.2）。

三条路都堵死，于是轮到标准库出的"官方答案"：contextvars。

四、contextvars 到底是什么

4.1 官方定义

This module provides APIs to manage, store, and access context-local state. ... Context managers that have state should use Context Variables instead of threading.local() to prevent their state from bleeding to other code unexpectedly, when used in concurrent code. —— Python 官方文档 · contextvars

两个关键词：context-local state（上下文局部状态）、bleeding to other code（渗透到别的代码）。它就是为了解决"并发下状态串号"而生的，3.7 版本引入，设计文档是 PEP 567。

4.2 用一个类比理解它

官方抽象的说法不好记，我更喜欢这个类比：

把每一个异步任务（Task）想成一个人，出发前会领到一个背包。 ContextVar 就是背包里的一个格子。 你 set() 就是往格子里放东西，get() 就是掏出来。 关键：任务在创建那一刻，会复制一份当前背包，从此各背各的。A 往自己背包里放东西，B 的背包不受影响。

用图表示：

flowchart TD
  E[&#34;事件循环（单线程）&#34;]
  E --> T1[&#34;Task A（请求 A）<br/>背包副本：user_id = 1&#34;]
  E --> T2[&#34;Task B（请求 B）<br/>背包副本：user_id = 2&#34;]
  T1 --> R1[&#34;工具读取 → 1 ✅&#34;]
  T2 --> R2[&#34;工具读取 → 2 ✅&#34;]

这就是它能做到"并发安全"的原因：隔离的粒度从"线程"降到了"任务"。

4.3 "复制背包"这件事，官方源码里写得很清楚

PEP 567 里直接给出了 asyncio Task 的实现片段，这属于"别人的源码"，比任何二手解释都可信：

class Task:
    def __init__(self, coro):
        ...
        # Get the current context snapshot.
        self._context = contextvars.copy_context()
        self._loop.call_soon(self._step, context=self._context)

    def _step(self, exc=None):
        ...
        # Every advance of the wrapped coroutine is done in
        # the task's context.
        self._loop.call_soon(self._step, context=self._context)

（来源：PEP 567 · asyncio）

翻译成一句话：Task 在 __init__ 里就 copy_context() 了一份快照，之后协程的每一步都在这个副本里跑。 所以：

  • 创建任务之前设置的值 → 任务能看见；
  • 创建任务之后再设置的值 → 任务看不见（它冻结的是创建那一刻的副本）。

asyncio 官方文档也是同样的措辞：

If no context is provided, the Task copies the current context and later runs its coroutine in the copied context. —— Python 官方文档 · asyncio Task

4.4 标准库文档里自带的例子

官方文档 "asyncio support" 一节有个很好的例子：一个 echo server，用 ContextVar 把客户端地址挂到处理该客户端的 Task 上，深层函数不用任何参数就能读到它：

import asyncio
import contextvars

client_addr_var = contextvars.ContextVar('client_addr')

def render_goodbye():
    # 不用显式传参，就能拿到"当前处理的客户端地址"
    client_addr = client_addr_var.get()
    return f'Good bye, client @ {client_addr}\r\n'.encode()

async def handle_request(reader, writer):
    addr = writer.transport.get_extra_info('socket').getpeername()
    client_addr_var.set(addr)          # 在任务入口 set
    ...
    writer.write(render_goodbye())     # 深层函数直接 get

（来源：Python 官方文档 · contextvars · asyncio support）

我们项目要做的，本质上是一模一样的模式，只不过把 client_addr 换成了 user_id。

4.5 set 会返回一个 Token，这是配套的"撤销键"

token = _current_user_id.set(user_id)   # 放进去，拿到一张"撤销凭证"
try:
    ...                                 # 中间干正事
finally:
    _current_user_id.reset(token)       # 用完撤销，恢复到 set 之前的值

官方对 reset 的说明：

Reset the context variable to the value it had before the ContextVar.set() that created the token was used. —— 同上

为什么要 reset 而不是简单 set(None)？因为如果上层已经设过一个值，你 set(None) 就把上层的值也冲掉了；只有 reset(token) 才能精确恢复到"设置之前"的状态。这个细节在第 6 章会再展开。

五、项目落地：一条链路上的五根接力棒

现在把概念落到代码。整个链路一共五步，每步都很短。

第 1 棒：定义 ContextVar（user_context.py）

# backend/app/services/user_context.py
from contextvars import ContextVar, Token

# 当前请求的用户 ID（None 表示匿名）
_current_user_id: ContextVar[int | None] = ContextVar("current_user_id", default=None)

def set_current_user_id(user_id: int | None) -> Token:
    """设置当前请求的用户 ID，返回用于恢复的 token。"""
    return _current_user_id.set(user_id)

def reset_current_user_id(token: Token) -> None:
    """恢复用户 ID 到设置前的值（配合 set 返回的 token 使用）。"""
    _current_user_id.reset(token)

def get_current_user_id() -> int | None:
    """读取当前请求的用户 ID。"""
    return _current_user_id.get()

注意一个细节：官方明确要求 ContextVar 要在模块顶层创建，不要写在闭包里——

Important: Context Variables should be created at the top module level and never in closures. —— Python 官方文档 · contextvars

原因是 Context 对象持有对 ContextVar 的强引用，放在闭包里会影响垃圾回收。我们这个变量就定义在模块顶层，符合要求。

第 2 棒：请求入口拿到 user_id（deps.py + chat.py）

身份来自 JWT。项目里用 FastAPI 依赖解析它：

# backend/app/core/deps.py
async def get_optional_user(
    token: Annotated[str | None, Depends(oauth2_scheme_optional)],
    db: Annotated[AsyncSession, Depends(get_db)],
) -> User | None:
    """可选鉴权：匿名返回 None。"""
    if not token:
        return None
    payload = decode_access_token(token)
    sub = payload.get("sub")
    return await db.scalar(select(User).where(User.id == int(sub)))

OptionalUser = Annotated[User | None, Depends(get_optional_user)]

路由里把它取出来，往下传：

# backend/app/routers/chat.py
@router.post("", response_model=dict)
async def chat(body: ChatRequest, current: OptionalUser = None) -> dict:
    user_id = current.id if current else None          # 登录→有值；匿名→None
    conversation_id = body.conversation_id or uuid.uuid4().hex[:16]
    history = await chat_history_service.get_recent_history(user_id, conversation_id)

    result = await agent.chat(body.message, user_id=user_id, history=history)
    ...

注意这里的设计很克制：user_id 还是通过参数传进 agent.chat() 的。contextvars 不是用来取代"上一层已知的参数传递"，而是用来解决"再往下、签名改不了"的那一段。这是个分寸问题，别一上来就把所有参数都塞进上下文。

第 3 棒：进入 Agent 时写进上下文（agent.chat）

# backend/app/services/agent.py
async def chat(user_input: str, user_id: int | None = None, history: list[dict] | None = None) -> dict:
    initial = _build_initial_state(user_input, history)
    token = set_current_user_id(user_id)      # ← 放进"背包"
    try:
        ag = await _get_agent()
        result = await ag.ainvoke(initial)    # ← 整条图都在这一个 Task 里，都能读到
        return {"intent": result.get("intent", ""), "answer": result.get("answer", "")}
    except Exception as exc:
        logger.exception("对话异常: %s", exc)
        return {"intent": "other", "answer": "抱歉，AI 服务暂时不可用，请稍后重试。"}
    finally:
        reset_current_user_id(token)          # ← 用完一定要还回去

这里能成立有一个前提：ag.ainvoke(...) 是 await 调用，没有 create_task。按传播规则，await 不会复制上下文，调用链共用一个 Context，所以图里的工具节点自然能读到。如果这里改成了 create_task 或丢到线程池，就要重新考虑（详见第 6 章）。

第 4 棒：工具内部直接读（local_tools.py）

# backend/app/services/local_tools.py
@tool
async def search_my_plans(query: str, top_k: int = 5) -> str:
    """在当前登录用户自己的私有知识库中检索……"""
    user_id = get_current_user_id()          # ← 从"背包"里掏出来，没有任何参数
    if user_id is None:
        return "当前未登录，无法检索个人知识库。请先登录后重试。"

    items = await user_knowledge_service.search(user_id, query.strip(), top_k)
    ...

看这个函数签名——search_my_plans(query, top_k)，干净得完全看不出它依赖用户身份。而它确实是按用户隔离的。这正是 contextvars 想要的效果：横切关注点（cross-cutting concern）不污染业务签名。

第 5 棒：落到 SQL，隔离在查询层（user_knowledge_service.py）

# backend/app/services/user_knowledge_service.py
stmt = text("""
    SELECT title, source, content, chunk_index,
           1 - (embedding <=> :vec::vector) AS similarity
    FROM user_knowledge
    WHERE user_id = :user_id AND embedding IS NOT NULL
    ORDER BY embedding <=> :vec::vector ASC
    LIMIT :top_k
""")

这里有一个重要的工程原则：多租户隔离要落在查询条件里，而不是靠应用层"记得过滤"。

如果只在 Python 层 if item.user_id == current_user_id: keep，一旦哪天新加了一条查询路径忘了写这个判断，就会漏数据。把 WHERE user_id = :user_id 写死在 SQL 里，隔离就成了 SQL 的语义，而不是人的记忆力。（多租户 RAG 的更多细节，是系列后面单独一篇的主题。）

把五根棒连起来

sequenceDiagram
  participant C as 客户端
  participant R as FastAPI 路由
  participant D as OptionalUser 依赖
  participant AG as agent.chat()
  participant CTX as ContextVar
  participant T as 本地工具
  participant DB as PostgreSQL

  C->>R: POST /api/v1/chat（携带 JWT）
  R->>D: 解析 token
  D-->>R: user_id = 7
  R->>AG: chat(msg, user_id=7)
  AG->>CTX: set_current_user_id(7)
  AG->>T: 图节点执行 search_my_plans()
  T->>CTX: get_current_user_id() → 7
  T->>DB: SELECT ... WHERE user_id = 7
  DB-->>T: 只返回用户 7 的分块
  AG->>CTX: finally: reset(token)

整条链路，工具签名零改动，Agent 图零改动，只多了 set / get / reset 三个调用。

六、边界：什么时候它会"失效"

这一章是本文最实用的部分。contextvars 不是万能的，它的传播规则如果不清楚，会踩得很惨。

6.1 一张速查表（建议收藏）

场景上下文是否自动传播说明
直接 await 调用协程✅ 是（同一个 Context）不复制，父子读写立即可见
asyncio.create_task()✅ 是（创建时复制一份）父级在创建之后再 set，子任务看不到
asyncio.to_thread()✅ 是（官方明确会传播）见 6.3
loop.run_in_executor()❌ 默认不传播需手动 copy_context().run
threading.Thread❌ 新线程是空上下文从零开始，继承不到任何值
子进程（如 MCP stdio）❌ 完全不共享进程边界，原理上就不可能

6.2 坑一：跨进程（本项目最核心的取舍）

这就是第二篇里那个结论的理论依据。MCP Server 跑在独立子进程，contextvars 是进程内的内存结构，跨不过进程边界。所以：

  • 需要 user_id 的 search_my_plans、check_itinerary_weather → 留在 Agent 进程内（本地工具）；
  • 不需要身份的天气、资讯、公共检索 → 走 MCP。

6.3 坑二：跨线程

把同步阻塞代码丢进线程池是很常见的优化。但要注意不同 API 的行为不一样：

  • asyncio.to_thread() 会传播上下文。官方文档原文：

    Also, the current contextvars.Context is propagated, allowing context variables from the event loop thread to be accessed in the separate thread. —— Python 官方文档 · asyncio · Running in threads

  • 但 loop.run_in_executor() / ThreadPoolExecutor 默认不会。新线程带着一个空上下文启动，读到的只能是默认值。PEP 567 里专门给了正确姿势——抓一份快照，让目标线程在这个快照里跑：

    executor = ThreadPoolExecutor()
current_context = contextvars.copy_context()
executor.submit(current_context.run, some_function)

    （来源：PEP 567 · Offloading execution to other threads）

一个常见的现象是：日志里的 request_id 在异步链路上好好的，一到某个线程池里就"随机丢失"——基本都是这个原因。

6.4 坑三：create_task 的时机

因为复制发生在创建的那一刻：

# ❌ 读不到
task = asyncio.create_task(do_work())   # 先创建，快照 = 当前（还没 set）
_current_user_id.set(7)                  # 后 set，包里那份快照已经冻结了

# ✅ 读得到
_current_user_id.set(7)                  # 先 set
task = asyncio.create_task(do_work())    # 后创建，快照包含 7

记住那个类比：背包是在"出发那一刻"拍照复制的，出发之后你再往自己包里塞东西，照片不会变。

6.5 坑四：忘记 reset

contextvars 的值不会因为函数返回而自动消失，它会一直留在当前 Context 里，直到你 reset 或者整个任务结束。在长生命周期的异步服务里，这会带来两个后果：

  1. 状态泄漏：同一个 Task 里后续的代码读到的还是上一个请求的值；
  2. 链条累积：旧请求的上下文没人清理，越积越多。

所以标准写法永远是 try/finally：

token = set_current_user_id(user_id)
try:
    ...
finally:
    reset_current_user_id(token)      # token 只能用一次；用 token，不要 set(None)

chat 和 chat_stream 两个入口都是这么写的——只要 set 了，就一定配一个 finally reset。

七、为什么这套做法在业界很常见

contextvars 不是这个项目发明的偏门技巧，它是异步 Python 世界的通用模式。你在别的地方一定见过同一个思路：

场景用什么干什么
结构化日志（structlog）structlog.contextvars把 request_id、user_id 绑到当前请求，日志自动带上
分布式追踪（OpenTelemetry）context propagation把 trace_id / span 沿调用链传播
Web 框架旧时代（Django/Flask）g / request 对象请求级数据的存放点（同步时代靠 thread-local）
我们这里ContextVar把 user_id 传给私有工具

它们解决的是同一个问题类别：请求级状态（request-scoped state）的跨层传递。区别只在"跨的是什么边界"——同任务的 await 免费，跨线程要手动搬，跨进程就别想了。

顺带一提，官方文档在"asyncio support"里说得很清楚：ContextVar 是"asyncio 原生支持、开箱即用"的。它本来就是为这个场景造的轮子，不用自己造。

八、小结与下一篇

可复用清单

  • 请求级的值（user_id、trace_id、语言…）用 ContextVar，别用全局变量。
  • ContextVar 定义在模块顶层，不要放闭包里。
  • set 一定配 finally: reset(token)；恢复用 token，不要 set(None)。
  • 记住传播边界：同任务 await 免费；create_task 看创建时机；线程池要 copy_context().run；子进程完全不通。
  • 多租户隔离落到 SQL 的 WHERE 里，别只靠应用层自觉。
  • 别滥用：上一层已知的参数就正常传参，contextvars 留给"签名改不了"的深层横切需求。

代码位置

backend/app/services/user_context.py（定义）、backend/app/core/deps.py（解析身份）、backend/app/routers/chat.py（入口）、backend/app/services/agent.py（set/reset）、backend/app/services/local_tools.py（读取）、backend/app/services/user_knowledge_service.py（查询层隔离）。

下一篇预告

工具能查数据了，"数据从哪来"就成了下一个问题。下一篇进 RAG：pgvector 的分块、1024 维对齐、余弦检索的工程细节，以及那个"embedding 挂了怎么办"的确定性伪向量兜底。

参考资料

  1. Python 官方文档 · contextvars — Context Variables
  2. PEP 567 – Context Variables（Yury Selivanov，Python 3.7）
  3. Python 官方文档 · asyncio Task 与上下文
  4. MCP 官方文档 · Architecture overview（"MCP is a stateless protocol"）
  5. structlog 官方文档 · Context Variables
  6. OpenTelemetry · Python 语言文档（context propagation）
avatar
文章
阅读
粉丝