Skip to main content
沙箱类工作区（Bubblewrap、Docker、E2B、Daytona、K8s、OpenSandbox）无法直接注册主机侧的 MCP 客户端：MCP 服务器运行在容器或沙箱内部，stdio 会话无法跨越这条边界。AgentScope 通过 MCP 网关解决这个问题：一个运行在工作区内部的轻量 FastAPI 进程，持有上游 MCP 会话，并通过一个带鉴权的 HTTP 端点统一暴露给主机。 网关暴露一组精简的 REST 接口（GET /health、GET/POST/DELETE /mcps、GET /mcps/{name}/tools、POST /mcps/{name}/tools/{tool}、PUT /mcps/{name}/runtime-headers），由每次 initialize() 时生成的工作区专属 Bearer 令牌保护。主机侧由两个适配器保持标准接口不变：
运行时更新 HTTP header 对网关代理同样可用，但代理必须已经连接，因为要更新的是网关侧那个活跃的客户端；connect 会把当时的运行时 header 一并带上注册，因此它们能在重连后继续生效。工作区镜像早于该端点、或网关重启导致活跃客户端不存在时，调用会抛出 RuntimeError。
这层抽象让智能体侧代码在所有工作区后端上保持一致：无论上游会话位于主机（LocalWorkspace）还是隔离环境（所有沙箱类工作区），工作区的 list_mcps() 返回的都是 MCPClient 实例。
网关不会发布在主机可达的网络端口上。每次主机到网关的调用都在沙箱内部执行：GatewayMCPClient 通过后端的 exec_shell 以 curl 命令发起请求，网关始终只监听沙箱自身的回环地址。由于沙箱没有对外监听的服务，这一设计避免了对外开放网关端口带来的攻击面。
BubblewrapWorkspace 是例外：它与主机共享网络命名空间，沙箱的回环地址即主机回环地址，主机上的其他进程有可能访问到该端口。因此它额外启用了两道防护：