Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
from __future__ import annotations
import asyncio
import atexit
import concurrent.futures
import contextvars
import hashlib
import importlib
import ipaddress
import json
import mimetypes
import os
import re
import shlex
import shutil
import socket
import subprocess
import sys
import threading
import time
import uuid
from contextlib import contextmanager
from functools import wraps
from typing import Any, Optional, get_type_hints
from urllib.parse import urlsplit, urlunsplit
from weakref import WeakKeyDictionary
from loggers import get_logger
from utils.account_context import (
OWNER_ACCOUNT_ID,
account_thread,
current_account_id,
is_owner_context,
)
from core.inference import mcp_images
logger = get_logger(__name__)
MCP_TOOL_PREFIX = "mcp__"
_WINDOWS_BATCH_ALWAYS_UNSAFE_ARGUMENT_CHARS = frozenset('%!"\r\n')
_WINDOWS_BATCH_UNQUOTED_UNSAFE_ARGUMENT_CHARS = frozenset("&|<>^()")
# -- and the chat send re-hung for the full timeout -- on every message. Cool off for this long after a failure; much
# Failed probes are not cached but cool off, so a down server doesn't hang every send.
FAILED_PROBE_COOLOFF_SECONDS = 60.0
OAUTH_FAILED_PROBE_COOLOFF_SECONDS = 300.0
_oauth_token_store = None
_account_oauth_token_stores: dict[str, Any] = {}
def _managed_mcp_restricted() -> bool:
return not is_owner_context()
def _account_key(value):
if is_owner_context():
return value
return current_account_id(), value
def _public_mcp_addresses(url: str) -> list[str]:
from fastapi import HTTPException
from core.inference.providers import _metadata_address, _metadata_host, managed_private_url_hint
from utils.managed_provider_url_settings import get_managed_private_provider_urls_allowed
private_allowed = get_managed_private_provider_urls_allowed()
detail = "Managed accounts may only use public-network HTTP MCP servers."
if not private_allowed:
detail += managed_private_url_hint()
try:
parsed = urlsplit(url)
if parsed.scheme not in ("http", "https") or not parsed.hostname:
raise ValueError("HTTP URL required")
if parsed.username is not None or parsed.password is not None:
raise ValueError("Use MCP headers for credentials")
host = parsed.hostname
if "%" in host:
raise ValueError("Scoped addresses are not public")
if _metadata_host(host):
raise ValueError("Cloud metadata address")
port = parsed.port or (443 if parsed.scheme == "https" else 80)
addresses = socket.getaddrinfo(host, port, type = socket.SOCK_STREAM)
if not addresses:
raise ValueError("No addresses")
for *_, sockaddr in addresses:
address = ipaddress.ip_address(sockaddr[0])
address = getattr(address, "ipv4_mapped", None) or address
if _metadata_address(str(address)):
raise ValueError("Cloud metadata address")
if private_allowed:
continue
if not address.is_global or address.is_multicast or address.is_reserved:
raise ValueError("Non-public address")
return list(dict.fromkeys(sockaddr[0] for *_, sockaddr in addresses))
except (OSError, ValueError, UnicodeError) as exc:
raise HTTPException(status_code = 400, detail = detail) from exc
def validate_mcp_address(url: str) -> None:
# Studio's own Decisions server is answered in process; with a local model no request leaves this machine.
if not _managed_mcp_restricted() or (is_studio_decisions(url) and _local_decisions()):
return
if is_studio_tools(url):
return
if is_stdio(url):
from fastapi import HTTPException
raise HTTPException(
status_code = 400,
detail = "Only the installation owner may register local-command MCP servers.",
)
_public_mcp_addresses(url)
def _public_http_client_factory(**kwargs):
"""Pin public destinations, including redirects and OAuth discovery; SNI keeps the original hostname and proxy env vars are ignored so they cannot reach the LAN."""
from mcp.shared._httpx_utils import create_mcp_http_client
client_type = get_type_hints(create_mcp_http_client)["return"]
http = importlib.import_module(client_type.__module__.split(".")[0])
class PublicTransport(http.AsyncBaseTransport):
def __init__(self):
# Separate pools retain TLS identity when two names resolve to one IP.
self.transports = {}
async def handle_async_request(self, request):
addresses = await asyncio.to_thread(_public_mcp_addresses, str(request.url))
origin = (request.url.scheme, request.url.host, request.url.port)
if origin not in self.transports:
self.transports[origin] = http.AsyncHTTPTransport(trust_env = False)
# localhost answers ::1 first while most local servers bind 127.0.0.1 only.
for index, address in enumerate(addresses):
pinned = http.Request(
method = request.method,
url = request.url.copy_with(host = address),
headers = request.headers,
stream = request.stream,
extensions = {**request.extensions, "sni_hostname": request.url.host},
)
try:
return await self.transports[origin].handle_async_request(pinned)
except (http.ConnectError, http.ConnectTimeout):
if index == len(addresses) - 1:
raise
async def aclose(self):
for transport in self.transports.values():
await transport.aclose()
kwargs["trust_env"] = False
kwargs["transport"] = PublicTransport()
kwargs.setdefault("follow_redirects", True)
if kwargs.get("timeout") is None:
kwargs["timeout"] = http.Timeout(30.0, read = 300.0)
return client_type(**kwargs)
def _tool_http_client_factory(**kwargs):
"""No read cap: _race_tool_call enforces each call's budget, which the SDK's 300s read timeout would cut short."""
if _managed_mcp_restricted():
client = _public_http_client_factory(**kwargs)
else:
from mcp.shared._httpx_utils import create_mcp_http_client
kwargs.pop("follow_redirects", None) # create_mcp_http_client sets its own redirect policy
client = create_mcp_http_client(**kwargs)
t = client.timeout
client.timeout = type(t)(connect = t.connect, read = None, write = t.write, pool = t.pool)
tracker = _SESSION_POSTS.get()
if tracker is not None:
tracker.install(client)
return client
class _PostSlot:
__slots__ = ("key", "token", "rid")
def __init__(self, key):
self.key, self.token, self.rid = key, None, None
class _PostTracker:
"""Open POSTs of a cached session, each bound to its call, so only an abandoned call's open reply counts."""
def __init__(self):
self.lock = threading.Lock()
self.open: set = set()
self.waiting: list = [] # dispatches whose POST is not sent yet, FIFO per (method, target)
self.abandoned: dict = {} # open POST token -> when its call was abandoned
self.bound: dict = {} # JSON-RPC id -> slot, so a redirected POST stays with its call
self.installed = False
def enqueue(self, slot: _PostSlot) -> None:
# Called on the session loop as the call starts, so the FIFO follows the order the SDK sends in.
if slot.key is not None:
with self.lock:
self.waiting.append(slot)
def settle(self, slot: _PostSlot, abandoned: bool) -> None:
with self.lock:
if slot in self.waiting:
self.waiting.remove(slot)
if abandoned and slot.token in self.open:
self.abandoned[slot.token] = time.monotonic()
elif not abandoned and self.bound.get(slot.rid) is slot:
del self.bound[slot.rid]
def pending(self) -> Optional[tuple]:
"""(oldest abandonment time, count) of abandoned replies still open, else None."""
with self.lock:
if not self.abandoned:
return None
return min(self.abandoned.values()), len(self.abandoned)
def _sent(self, token, key, rid) -> None:
with self.lock:
self.open.add(token)
slot = self.bound.get(rid)
if slot is not None and slot.key == key:
slot.token = token
return
for slot in self.waiting:
if slot.key == key:
slot.token, slot.rid = token, rid
self.waiting.remove(slot)
self.bound[rid] = slot
break
def _closed(self, token) -> None:
with self.lock:
self.open.discard(token)
self.abandoned.pop(token, None)
def install(self, client) -> None:
http = sys.modules[
type(client).__module__.split(".")[0]
] # already imported: it built ``client``
tracker = self
class Stream(http.AsyncByteStream):
def __init__(self, inner, token):
self.inner, self.token = inner, token
async def __aiter__(self):
async for chunk in self.inner:
yield chunk
async def aclose(self):
try:
await self.inner.aclose()
finally:
tracker._closed(self.token)
class Transport(http.AsyncBaseTransport):
def __init__(self, inner):
self.inner = inner
async def handle_async_request(self, request):
if request.method != "POST":
return await self.inner.handle_async_request(request)
token, (key, rid) = object(), _rpc_target(request)
if key is None or key[0] not in ("tools/call", "resources/read"):
# Only a call's reply may outlive the SDK's old read cap; probes and handshakes keep it.
request.extensions["timeout"] = {
**request.extensions.get("timeout", {}),
"read": _ABANDONED_REPLY_TIMEOUT,
}
tracker._sent(token, key, rid)
try:
response = await self.inner.handle_async_request(request)
except BaseException:
tracker._closed(token)
raise
response.stream = Stream(response.stream, token)
return response
async def aclose(self):
await self.inner.aclose()
# httpx has no public hook for a request ending without a response; unwrappable clients keep the deadline.
if not hasattr(client, "_transport") or not isinstance(
getattr(client, "_mounts", None), dict
):
return
client._transport = Transport(client._transport)
client._mounts = {k: (v if v is None else Transport(v)) for k, v in client._mounts.items()}
self.installed = True
def _rpc_target(request) -> tuple:
"""((JSON-RPC method, tool name or URI), id) of a request POST, else (None, None)."""
try:
msg = json.loads(request.content)
if "id" not in msg or "method" not in msg:
return None, None
params = msg.get("params") or {}
return (msg["method"], params.get("name") or params.get("uri")), msg["id"]
except Exception: # noqa: BLE001
return None, None
# Set by _McpSession.connect so _tool_http_client_factory can hook the client the SDK builds for that session.
_SESSION_POSTS: contextvars.ContextVar[Optional[_PostTracker]] = contextvars.ContextVar(
"mcp_session_posts", default = None
)
def is_stdio(address: str) -> bool:
"""A non-HTTP address is a local stdio command, e.g. 'npx -y
@modelcontextprotocol/server-filesystem /path'."""
return not address.strip().lower().startswith(("http://", "https://"))
def _split_windows_command_line(address: str) -> list[str]:
"""Parse Windows argv by the rules list2cmdline() writes, so trailing backslashes stay undoubled."""
parts: list[str] = []
current: list[str] = []
in_quotes = False
backslashes = 0
arg_started = False
i = 0
while i < len(address):
ch = address[i]
if ch == "\\":
backslashes += 1
i += 1
continue
if ch == '"':
current.extend("\\" * (backslashes // 2))
if backslashes % 2:
current.append('"')
else:
in_quotes = not in_quotes
arg_started = True
backslashes = 0
i += 1
continue
# list2cmdline splits only on space and tab; other Unicode or control whitespace is argument data and must not be split.
if ch in (" ", "\t") and not in_quotes:
if backslashes:
current.extend("\\" * backslashes)
arg_started = True
backslashes = 0
if arg_started or current:
parts.append("".join(current))
current = []
arg_started = False
i += 1
while i < len(address) and address[i] in (" ", "\t"):
i += 1
continue
if backslashes:
current.extend("\\" * backslashes)
arg_started = True
backslashes = 0
current.append(ch)
arg_started = True
i += 1
if backslashes:
current.extend("\\" * backslashes)
arg_started = True
if in_quotes:
raise ValueError("No closing quotation")
if arg_started or current:
parts.append("".join(current))
return parts
def parse_stdio_command(address: str) -> list[str]:
"""Split a stdio command line into argv, shared so validation and transport quote alike."""
posix = sys.platform != "win32"
if posix:
return shlex.split(address, posix = posix)
if address.lstrip().startswith("'"):
raise ValueError("Single-quoted executables are not supported on Windows")
return _split_windows_command_line(address)
def join_stdio_command(parts: list[str]) -> str:
"""Inverse of parse_stdio_command: list2cmdline on Windows so paths round-trip, shlex.join elsewhere."""
if sys.platform == "win32":
return subprocess.list2cmdline(parts)
return shlex.join(parts)
def _windows_batch_argument_is_unsafe(argument: str) -> bool:
if _WINDOWS_BATCH_ALWAYS_UNSAFE_ARGUMENT_CHARS.intersection(argument):
return True
serialized = subprocess.list2cmdline([argument])
is_quoted = serialized.startswith('"') and serialized.endswith('"')
return not is_quoted and bool(
_WINDOWS_BATCH_UNQUOTED_UNSAFE_ARGUMENT_CHARS.intersection(argument)
)
def _session_log_id(url: str) -> str:
"""Non-secret log label: never log the raw address, since argv and query can hold credentials;
use the executable basename or host plus a short digest"""
digest = hashlib.sha256(url.encode()).hexdigest()[:12]
if not is_stdio(url):
try:
label = urlsplit(url).hostname or "<url>"
except Exception: # noqa: BLE001
label = "<invalid>"
return f"{label}#{digest}"
try:
parts = parse_stdio_command(url)
exe = os.path.basename(parts[0]) if parts else "<empty>"
except Exception: # noqa: BLE001
exe = "<invalid>"
return f"{exe}#{digest}"
def stdio_mcp_enabled() -> bool:
"""Stdio MCP spawns local processes outside the sandbox: loopback only via UNSLOTH_STUDIO_ALLOW_STDIO_MCP; Colab and network binds off unless set."""
if _managed_mcp_restricted():
return False
if os.environ.get("UNSLOTH_STUDIO_ALLOW_STDIO_MCP") != "1":
return False
from state.tool_policy import get_tool_policy
from utils.host_policy import loopback_default_active, remote_connector_active
if loopback_default_active() and (remote_connector_active() or get_tool_policy() is False):
return False
return True
def stdio_mcp_disabled_reason() -> str:
"""Must name the actual cause: the env var would enable local commands on a published API."""
if _managed_mcp_restricted():
return "Only the installation owner may register local-command MCP servers."
from state.tool_policy import get_tool_policy
from utils.host_policy import loopback_default_active, remote_connector_active
if os.environ.get("UNSLOTH_STUDIO_ALLOW_STDIO_MCP") == "1" and loopback_default_active():
if remote_connector_active():
return (
"Local commands are disabled while Remote Access is on, because the "
"server is reachable from outside this machine. Turn off Remote Access "
"to use local MCP servers, or use an http:// or https:// URL instead."
)
if get_tool_policy() is False:
return (
"Local commands are disabled because tools are disabled for this "
"server. Restart without --disable-tools, or use an http:// or "
"https:// URL instead."
)
return (
"Local commands aren't enabled on this server. To allow them, set "
"UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1 and restart Unsloth, or use an "
"http:// or https:// URL instead."
)
# OAuth needs minutes for browser sign-in; stdio allows first-run package download.
_HTTP_PROBE_TIMEOUT = 8.0
_OAUTH_PROBE_TIMEOUT = 305.0
_STDIO_PROBE_TIMEOUT = 60.0
def probe_timeout(address: str, use_oauth: bool) -> float:
if use_oauth:
return _OAUTH_PROBE_TIMEOUT
return _STDIO_PROBE_TIMEOUT if is_stdio(address) else _HTTP_PROBE_TIMEOUT
def parse_server_headers(server: dict) -> Optional[dict]:
"""Parsed headers_json; for stdio servers this dict is the process env, not HTTP headers."""
raw = server.get("headers_json")
if not raw:
return None
try:
parsed = json.loads(raw)
except (json.JSONDecodeError, ValueError):
return None
return parsed if isinstance(parsed, dict) else None
def _oauth_store():
global _oauth_token_store
if not is_owner_context():
from key_value.aio._utils.sanitization import AlwaysHashStrategy
from key_value.aio.stores.filetree import FileTreeStore
from utils.paths.storage_roots import account_path, ensure_dir
account_id = current_account_id()
if account_id not in _account_oauth_token_stores:
_account_oauth_token_stores[account_id] = FileTreeStore(
data_directory = ensure_dir(account_path("mcp-oauth-tokens")),
key_sanitization_strategy = AlwaysHashStrategy(),
collection_sanitization_strategy = AlwaysHashStrategy(),
)
return _account_oauth_token_stores[account_id]
if _oauth_token_store is None:
from key_value.aio._utils.sanitization import AlwaysHashStrategy
from key_value.aio.stores.filetree import FileTreeStore
from utils.paths.storage_roots import ensure_dir, studio_root
# Hash keys: FileTreeStore treats '://' in raw URLs as nested directories.
_oauth_token_store = FileTreeStore(
data_directory = ensure_dir(studio_root() / "mcp-oauth-tokens"),
key_sanitization_strategy = AlwaysHashStrategy(),
collection_sanitization_strategy = AlwaysHashStrategy(),
)
return _oauth_token_store
def _strip_client_id_under_basic_auth(auth) -> None:
"""The SDK leaves client_id in the body under Basic auth; strict servers (Notion) read that as
two auth methods -- RFC 6749 2.3 -- and 401. Safe to drop: 3.2.1 makes client_id a MAY once
authenticated, and an unauthenticated client sends no header, so it keeps it."""
context = getattr(auth, "context", None)
prepare = getattr(context, "prepare_token_auth", None)
if prepare is None:
logger.warning("MCP OAuth: prepare_token_auth missing; client_id fixup skipped")
return
def prepare_token_auth(data, headers = None):
data, headers = prepare(data, headers)
if "Authorization" in headers:
data = {k: v for k, v in data.items() if k != "client_id"}
return data, headers
try:
context.prepare_token_auth = prepare_token_auth
except Exception as exc: # noqa: BLE001
# The SDK reach-in must never break OAuth: without it only strict servers fail, as before.
logger.warning("MCP OAuth: client_id fixup could not be applied: %s", exc)
def _oauth(
url: str,
oauth_client_id: Optional[str] = None,
oauth_client_secret: Optional[str] = None,
):
from fastmcp.client.auth import OAuth
# A pre-registered client skips Dynamic Client Registration (Google's MCP servers have no /register).
auth = OAuth(
mcp_url = url,
token_storage = _oauth_store(),
client_id = oauth_client_id,
client_secret = oauth_client_secret,
)
_strip_client_id_under_basic_auth(auth)
return auth
async def clear_oauth_tokens_async(url: str) -> None:
"""Must clear tokens on delete, URL change or OAuth disable: fastmcp keys them by URL, so a re-register reuses the old token; errors must not 500."""
try:
await _oauth(url).token_storage_adapter.clear()
except Exception as exc: # noqa: BLE001
logger.warning("Failed to clear OAuth tokens for %s: %s", url, exc)
_IS_WINDOWS = os.name == "nt"
_NODE_COMMANDS = frozenset({"node", "npm", "npx"})
_WINDOWS_LAUNCHER_SUFFIXES = (".cmd", ".exe", ".bat", ".ps1")
def _launcher_name(command: str) -> str:
"""argv[0] reduced to its bare launcher name, Windows suffix stripped."""
name = os.path.basename(command).lower()
for suffix in _WINDOWS_LAUNCHER_SUFFIXES:
if name.endswith(suffix):
return name[: -len(suffix)]
return name
def _is_node_command(command: str) -> bool:
"""Whether argv[0] is a Node launcher, the only kind given the managed runtime."""
return _launcher_name(command) in _NODE_COMMANDS
def _command_selects_runtime(command: Optional[str]) -> bool:
"""A path to a ``node`` launcher picks the runtime explicitly and runs regardless of PATH, so
handing its children a different Node would only split the two."""
return (
command is not None and bool(os.path.dirname(command)) and _launcher_name(command) == "node"
)
def _runtime_requirements(command: Optional[str]) -> tuple[bool, bool]:
"""Each launcher checks only what it runs, so npx never needs a separate npm executable on PATH."""
name = _launcher_name(command) if command is not None else None
if name == "node":
return False, False
if command is not None and os.path.dirname(command):
return False, False
if name == "npm":
return True, False
if name == "npx":
return False, True
return True, True
def _path_key(env: dict) -> str:
"""The env key holding PATH; Windows names are case-insensitive, so match any case there."""
if _IS_WINDOWS:
for key in env:
if key.upper() == "PATH":
return key
return "PATH"
def _stdio_env(headers: Optional[dict], command: Optional[str] = None) -> Optional[dict]:
"""Stdio env: own vars plus the managed Node bin on PATH, so npx runs without system Node."""
env = dict(headers or {})
for key, value in env.items():
if not isinstance(key, str) or not isinstance(value, str):
raise ValueError("stdio environment names and values must be strings")
if "\x00" in key or "\x00" in value:
raise ValueError("stdio environment must not contain NUL characters")
if "=" in key:
raise ValueError("stdio environment variable names must not contain '='")
key = _path_key(env)
base = env.get(key)
if isinstance(base, str) and not base:
# An explicitly empty PATH is a deliberate sandbox: hand it over untouched.
return env
if command is not None and not _is_node_command(command):
return env or None
if _command_selects_runtime(command):
return env or None
if not isinstance(base, str):
base = os.environ.get("PATH", "")
try:
from utils.node_runtime import path_with_managed_node
require_npm, require_npx = _runtime_requirements(command)
patched = path_with_managed_node(base, require_npm = require_npm, require_npx = require_npx)
except (ImportError, OSError, ValueError):
patched = base
if patched and patched != env.get(key):
env[key] = patched
return env or None
def _stdio_argv(parts: list, env: Optional[dict]) -> list:
"""argv with argv[0] resolved against the child's PATH. Windows resolves the command against the
parent environment before ``env`` applies, so a managed-only ``npx`` has to be handed over as
a full path."""
path_key = _path_key(env or {})
explicit_path = env is not None and path_key in env
path = (env or {}).get(path_key)
if not isinstance(path, str):
path = os.environ.get("PATH", "")
try:
resolved = shutil.which(parts[0], path = path)
except OSError:
resolved = None
if _IS_WINDOWS and resolved is None and explicit_path and not os.path.dirname(parts[0]):
raise ValueError(f"Cannot find {parts[0]!r} on the MCP server's configured PATH")
executable = resolved or parts[0]
if _IS_WINDOWS:
suffix = os.path.splitext(executable)[1].lower()
if suffix in {".cmd", ".bat"} and _launcher_name(executable) in {"npm", "npx"}:
launcher_dir = os.path.dirname(executable)
cli = os.path.join(
launcher_dir,
"node_modules",
"npm",
"bin",
f"{_launcher_name(executable)}-cli.js",
)
sibling_node = os.path.join(launcher_dir, "node.exe")
try:
node = (
sibling_node
if os.path.isfile(sibling_node)
else shutil.which("node", path = path)
)
cli_exists = os.path.isfile(cli)
except OSError:
node = None
cli_exists = False
if node and cli_exists:
# bypass cmd.exe so shell metacharacters remain literal argv.
return [node, cli, *parts[1:]]
raise ValueError(
f"Cannot launch {executable!r} without its Node executable and npm CLI script"
)
if suffix in {".cmd", ".bat"} and any(
_windows_batch_argument_is_unsafe(argument) for argument in parts[1:]
):
raise ValueError(
"Windows batch launchers cannot safely preserve these MCP command arguments; "
"invoke the executable directly, or use node.exe with the JavaScript entry point"
)
return [executable, *parts[1:]]
def _local_decisions() -> bool:
from core.systemone.catalog import parse_connection
from utils.systemone_settings import get_model
return parse_connection(get_model()) is None
def is_studio_decisions(url: str) -> bool:
from routes.systemone import MCP_PATH
from utils.host_policy import is_loopback_host
parts = urlsplit(url)
return (
parts.scheme == "http"
and is_loopback_host(parts.hostname or "")
and parts.path.rstrip("/") == MCP_PATH
)
def is_studio_tools(url: str) -> bool:
from core.inference.studio_tools_mcp import STUDIO_TOOLS_MCP_PATH
from utils.host_policy import is_loopback_host
try:
parts = urlsplit(url)
host = parts.hostname or ""
except ValueError:
return False
return (
parts.scheme == "http"
and is_loopback_host(host)
and parts.path.rstrip("/") == STUDIO_TOOLS_MCP_PATH
)
def _client(
url: str,
headers: Optional[dict],
use_oauth: bool = False,
**oauth,
):
validate_mcp_address(url)
from fastmcp import Client
if is_studio_decisions(url):
from routes.systemone import decisions_mcp
return Client(decisions_mcp)
if is_studio_tools(url):
# Listing only: calls go through studio_tools_mcp.call, which binds the caller.
from core.inference.studio_tools_mcp import chat_tools_mcp
return Client(chat_tools_mcp())
if is_stdio(url):
# Belt-and-suspenders: never spawn unless stdio is enabled on this host.
if not stdio_mcp_enabled():
raise PermissionError("stdio MCP servers are disabled on this host")
from fastmcp.client.transports import StdioTransport
parts = parse_stdio_command(url)
if not parts:
raise ValueError(f"Empty stdio command: {url!r}")
# keep_alive=False tears the subprocess down so a one-shot call leaves no orphan.
env = _stdio_env(headers, parts[0])
argv = _stdio_argv(parts, env)
return Client(
StdioTransport(
command = argv[0],
args = argv[1:],
env = env,
keep_alive = False,
)
)
from fastmcp.client.transports import SSETransport, StreamableHttpTransport
from fastmcp.mcp_config import infer_transport_type_from_url
auth = _oauth(url, **oauth) if use_oauth else None
transport_cls = (
SSETransport if infer_transport_type_from_url(url) == "sse" else StreamableHttpTransport
)
if _managed_mcp_restricted() and auth is not None:
auth.httpx_client_factory = _public_http_client_factory
return Client(
transport_cls(
url = url,
headers = headers or None,
auth = auth,
httpx_client_factory = _tool_http_client_factory,
)
)
def oauth_client_kwargs(row: dict) -> dict:
# Empty unless configured, so test doubles of _client without these kwargs keep working.
if not row.get("oauth_client_id"):
return {}
return {
"oauth_client_id": row["oauth_client_id"],
"oauth_client_secret": row.get("oauth_client_secret"),
}
_SESSION_IDLE_TTL = 300.0
_SESSION_REAP_INTERVAL = 30.0
_STDIO_CONNECT_TIMEOUT = 60.0 # allows first-run `npx -y ...` package download
_SESSION_CLOSE_TIMEOUT = 10.0
_SESSION_WEDGE_MARGIN = 15.0
_SESSION_LIVENESS_TIMEOUT = 5.0
_CANCEL_UNWIND_TIMEOUT = 2.0
# With no read cap, a still-open abandoned reply is bounded by retiring its session after the old cap or a pile-up.
_ABANDONED_REPLY_TIMEOUT = 300.0
_MAX_ABANDONED_REPLIES = 8
# Idle HTTP sessions are re-proved with tools/list before the next dispatch, as servers may expire
# them (MCP lets a server terminate a session at any time) and no HTTP liveness probe exists
_HTTP_IDLE_RECHECK = 30.0
_DEFAULT_MAX_SESSIONS = 32
def _max_sessions_from_env() -> int:
# Legacy stdio-specific name; still honoured for existing deployments.
raw = os.environ.get("UNSLOTH_STUDIO_MAX_MCP_SESSIONS")
if raw is None:
raw = os.environ.get("UNSLOTH_STUDIO_MAX_STDIO_MCP_SESSIONS")
if raw is None:
return _DEFAULT_MAX_SESSIONS
try:
return max(1, int(raw))
except ValueError:
return _DEFAULT_MAX_SESSIONS
_MAX_SESSIONS = _max_sessions_from_env()
def _connect_window(url: str, timeout: Optional[float]) -> Optional[float]:
"""Only stdio gets the cold-start cap, since its first run may download a package; HTTP does not."""
if timeout is None or not is_stdio(url):
return timeout
return min(timeout, _STDIO_CONNECT_TIMEOUT)
class _ConnectTimeout(asyncio.TimeoutError):
"""Ran out of time before the transport was up. Carries the window that actually expired, which
is not the caller's timeout when stdio's cold-start cap is the tighter bound."""
def __init__(self, window: Optional[float]):
super().__init__()
self.window = window
def _is_tool_error(exc: BaseException) -> bool:
"""Version-safe: fastmcp 3.0.2 has no dead probe. ToolError (tool ran and errored) leaves the
transport alive, so the session is kept; other call_tool errors are transport-level"""
try:
from fastmcp.exceptions import ToolError
except Exception: # noqa: BLE001
return False
return isinstance(exc, ToolError)
def _is_protocol_error(exc: BaseException) -> bool:
"""A JSON-RPC error proves the connection is alive, so it must not retire the session."""
for module, name in (
("mcp.shared.exceptions", "MCPError"),
("mcp.shared.exceptions", "McpError"),
):
try:
cls = getattr(__import__(module, fromlist = [name]), name, None)
except Exception: # noqa: BLE001
continue
if cls is not None and isinstance(exc, cls):
# Only when the server sent an error object, not for a synthetic MCPError.
return getattr(exc, "error", None) is not None
return False
# HTTP 404 for an unknown Mcp-Session-Id, so the request never ran: the client SDK's "Session terminated"
# stand-in, or the server body mcp 2.x relays (Python SDK -32600 / TypeScript SDK -32001 "Session not found").
_SESSION_GONE_MESSAGES = ("Session terminated", "Session not found")
_SESSION_GONE_CODES = (32600, -32600, -32001)
def _is_session_terminated(exc: BaseException) -> bool:
error = getattr(exc, "error", None)
return (
_is_protocol_error(exc)
and getattr(error, "message", None) in _SESSION_GONE_MESSAGES
and getattr(error, "code", None) in _SESSION_GONE_CODES
)
def _transport_dead(session) -> bool:
"""Only stdio can prove a transport dead; HTTP always reads unknown, so this returns False there."""
client = getattr(session, "client", None)
if client is None:
return True
transport = getattr(client, "transport", None)
probe = getattr(transport, "_is_session_dead", None)
if callable(probe):
try:
if probe():
return True
except Exception: # noqa: BLE001
pass
connect_task = getattr(transport, "_connect_task", None)
if connect_task is not None:
try:
if connect_task.done():
return True
except Exception: # noqa: BLE001
pass
return False
def _needs_idle_recheck(session, idle_for: float, remaining: Optional[float]) -> bool:
"""Idle HTTP sessions are re-proved since a server may drop one silently; stdio is exempt; skipped when the budget is too small to afford the probe."""
if is_stdio(session.url):
return False
# Negative means this borrower connected the session itself, so the handshake it just completed is proof enough.
if idle_for < 0.0 or idle_for < _HTTP_IDLE_RECHECK:
return False
return remaining is None or remaining > _SESSION_LIVENESS_TIMEOUT * 2
def _session_responsive(
session,
budget: Optional[float] = None,
cancel_event = None,
timeout_is_fatal: bool = True,
) -> bool:
"""Silence condemns a dirty session; an idle one retires only on definite failure; probe is one raw tools/list page, not ping or auto-paginating list_tools."""
client = session.client
if client is None:
return False
window = _SESSION_LIVENESS_TIMEOUT if budget is None else min(_SESSION_LIVENESS_TIMEOUT, budget)
if window <= 0:
# No budget left to ask in; that is not evidence either way.
return not timeout_is_fatal
probe = getattr(client, "list_tools_mcp", None) or client.list_tools
try:
# margin=0: a wedged loop must fail inside the window, not 15s past it.
session.run(_race_tool_call(probe(), window, cancel_event), window, margin = 0.0)
except _MCPCancelled:
raise
except (asyncio.TimeoutError, _SessionWedged):
return not timeout_is_fatal
except Exception as exc: # noqa: BLE001
# A JSON-RPC error means the transport works; reconnecting would lose session state.
if _is_session_terminated(exc) or not _is_protocol_error(exc):
return False
session.dirty = False
session.proved_at = time.monotonic()
return True
class _SessionWedged(Exception):
pass
class _SessionClosed(Exception):
"""The session was closed (server update/delete/shutdown) mid-call."""
def _abort_future(future) -> None:
# Let the cancelled coroutine unwind before its loop is stopped.
future.cancel()
try:
future.result(1.0)
except BaseException: # noqa: BLE001
pass
class _McpSession:
def __init__(
self,
url: str,
headers: Optional[dict],
use_oauth: bool = False,
):
# Cached sessions carry no auth; fail loudly rather than talk to an OAuth server unauthenticated.
if use_oauth and not is_stdio(url):
raise ValueError("OAuth MCP servers cannot use a shared session")
self.url = url
self.account_id = current_account_id()
self.headers = headers
self.client = None
self.closed = threading.Event()
self.defunct = False # discarded; close once in_flight drains (see _retire)
self.dirty = False # a call was abandoned on it; ping before reuse
self.abandoned_at: Optional[float] = None
self.abandoned = 0
self.posts = _PostTracker()
self._close_lock = threading.Lock()
self.call_lock = threading.Lock()
# stdio is one ordered byte stream; HTTP POSTs can run in parallel.
self.serialize_calls = is_stdio(url)
self.last_used = time.monotonic()
# Measured from proof of life, not checkout, so a concurrent borrower still sees the idle gap.
self.proved_at = self.last_used
self.in_flight = 0 # guarded by _mcp_sessions_lock
# Windows: force ProactorEventLoop; SelectorEventLoop cannot spawn subprocesses.
if sys.platform == "win32":
self.loop = asyncio.ProactorEventLoop()
else:
self.loop = asyncio.new_event_loop()
self._thread = account_thread(target = self._run_loop, name = "mcp-session", daemon = True)
self._thread.start()
def note_abandoned(self, slot: _PostSlot) -> None:
"""Record a call abandoned mid-flight on an HTTP transport (stdio has no reply socket to leak)."""
if is_stdio(self.url):
return
if self.posts.installed:
self.posts.settle(slot, abandoned = True)
return
if self.abandoned_at is None:
self.abandoned_at = time.monotonic()
self.abandoned += 1
def abandoned_overdue(self, now: Optional[float] = None) -> bool:
"""Whether still-open abandoned replies require closing the session rather than probing it."""
now = time.monotonic() if now is None else now
if self.posts.installed:
pending = self.posts.pending()
if pending is None:
return False
oldest, count = pending
elif self.abandoned_at is None:
return False
else:
oldest, count = self.abandoned_at, self.abandoned
return count >= _MAX_ABANDONED_REPLIES or now - oldest >= _ABANDONED_REPLY_TIMEOUT
def _run_loop(self) -> None:
asyncio.set_event_loop(self.loop)
try:
self.loop.run_forever()
finally:
self.loop.close()
def connect(self, timeout: Optional[float], cancel_event) -> None:
async def _open():
_SESSION_POSTS.set(self.posts)
client = _client(self.url, self.headers)
await client.__aenter__()
# No await between: close() must see the client after a racing abort.
self.client = client
return client
future = asyncio.run_coroutine_threadsafe(_open(), self.loop)
# timeout=None is no connect deadline; else _connect_window() caps stdio at its cold-start limit.
window = _connect_window(self.url, timeout)
deadline = None if window is None else time.monotonic() + window
while True:
if cancel_event is not None and cancel_event.is_set():
_abort_future(future)
raise _MCPCancelled
try:
future.result(0.05)
return
except (concurrent.futures.TimeoutError, asyncio.TimeoutError):
if future.done():
raise # the connect itself failed fast; don't wait out the window
if deadline is not None and time.monotonic() >= deadline:
_abort_future(future)
raise _ConnectTimeout(window)
def is_connected(self) -> bool:
client = self.client
if client is None:
return False
probe = getattr(client, "is_connected", None)
try:
return bool(probe()) if callable(probe) else True
except Exception:
return False
def run(
self,
coro,
timeout: Optional[float],
margin: float = _SESSION_WEDGE_MARGIN,
):
self.last_used = time.monotonic()
future = asyncio.run_coroutine_threadsafe(coro, self.loop)
# Margin only catches a wedged loop; poll so a closed session can't hang forever.
deadline = None if timeout is None else time.monotonic() + timeout + margin
try:
while True:
try:
return future.result(0.25)
except concurrent.futures.CancelledError:
# Only close() cancels in-flight tasks (in _shutdown).
raise _SessionClosed
except (concurrent.futures.TimeoutError, asyncio.TimeoutError):
if future.done():
raise # the call's own timeout; the session stays usable
if self.closed.is_set():
future.cancel()
raise _SessionClosed
if deadline is not None and time.monotonic() >= deadline:
future.cancel()
raise _SessionWedged
finally:
self.last_used = time.monotonic()
def close(self) -> None:
# Setting `closed` first also unblocks run() waiters (they poll it).
with self._close_lock:
if self.closed.is_set():
return
self.closed.set()
loop = getattr(self, "loop", None)
loop_alive = loop is not None and not loop.is_closed()
if loop_alive:
async def _shutdown() -> None:
# On the loop thread, it serializes with an aborted connect() that finished.
client, self.client = self.client, None
if client is not None:
await client.__aexit__(None, None, None)
# Cancel in-flight calls so they unwind before loop.stop; closed has already released run() waiters.
for task in asyncio.all_tasks():
if task is not asyncio.current_task():
task.cancel()
try:
asyncio.run_coroutine_threadsafe(_shutdown(), loop).result(_SESSION_CLOSE_TIMEOUT)
except Exception as exc: # noqa: BLE001
logger.warning(
"MCP session close failed for %s: %s",
_session_log_id(getattr(self, "url", "")),
exc,
)
try:
loop.call_soon_threadsafe(loop.stop)
except RuntimeError:
pass
else:
self.client = None
thread = getattr(self, "_thread", None)
if thread is not None:
thread.join(timeout = 5.0)
_mcp_sessions: dict[tuple, _McpSession] = {}
# Per-key locks so a slow connect/close never blocks unrelated servers; the global lock only guards the dicts.
class _McpKeyLock:
"""A per-key lock that can be removed once nobody references it."""
def __init__(self) -> None:
self.lock = threading.Lock()
self.users = 0 # guarded by _mcp_sessions_lock
_mcp_key_locks: dict[tuple, _McpKeyLock] = {}
_mcp_sessions_lock = threading.Lock()
_mcp_reaper_started = False
# Sessions discarded while somebody else was mid-call, closed by one worker off the request path. See _close_detached.
_mcp_cleanup_lock = threading.Lock()
_mcp_cleanup_queue: list = []
# Depth past which an evicting caller closes the overflow itself. See _close_detached.
_MAX_PENDING_CLOSES = 8
# How wide close_mcp_sessions fans out. See _close_all.
_MAX_CLOSE_THREADS = 16
_mcp_cleanup_worker: Optional[threading.Thread] = None
# Bumped on every close so an in-flight connect discards its session instead of publishing it.
_mcp_close_all_gen = 0
_mcp_account_close_gen: dict[str, int] = {}
_mcp_url_close_gen: dict[str | tuple[str, str], int] = {}
_mcp_cfg_close_gen: dict[str | tuple[str, str], int] = {}
_mcp_connects_in_flight = 0
_ANY_HEADERS = object()
def _headers_key(headers: Optional[dict]) -> tuple:
return tuple(sorted((headers or {}).items()))
def _url_close_key(url: str) -> str | tuple[str, str]:
# Key by digest: commands/URLs/env may hold secrets and these maps are never pruned.
return _account_key(hashlib.sha256(url.encode()).hexdigest())
def _cfg_close_key(url: str, headers: Optional[dict]) -> str | tuple[str, str]:
return _account_key(hashlib.sha256(repr((url, _headers_key(headers))).encode()).hexdigest())
def _mcp_close_generation(url: str, headers: Optional[dict]) -> tuple[tuple[int, int], int, int]:
return (
(_mcp_close_all_gen, _mcp_account_close_gen.get(current_account_id(), 0)),
_mcp_url_close_gen.get(_url_close_key(url), 0),
_mcp_cfg_close_gen.get(_cfg_close_key(url, headers), 0),
)
def _session_key(url: str, headers: Optional[dict], scope: Optional[str]) -> tuple:
return (url, _headers_key(headers), scope or "", current_account_id())
def _checkout_session(key: tuple) -> tuple[Optional[_McpSession], float]:
"""Returns the idle gap, not stored on the session, since concurrent borrowers would overwrite it."""
session = _mcp_sessions.get(key)
if session is not None and session.is_connected():
now = time.monotonic()
idle_for = now - session.proved_at
session.last_used = now
session.in_flight += 1
return session, idle_for
return None, -1.0
def _borrow_key_lock(key: tuple) -> _McpKeyLock:
"""Return a stable per-key lock while a caller waits for/connects it."""
key_lock = _mcp_key_locks.setdefault(key, _McpKeyLock())
key_lock.users += 1
return key_lock
def _discard_key_lock(key: tuple) -> None:
key_lock = _mcp_key_locks.get(key)
if key_lock is not None and key_lock.users == 0 and key not in _mcp_sessions:
_mcp_key_locks.pop(key, None)
def _return_key_lock(key: tuple, key_lock: _McpKeyLock) -> None:
with _mcp_sessions_lock:
key_lock.users -= 1
_discard_key_lock(key)
@contextmanager
def _connect_slot(url: str, headers: Optional[dict]):
global _mcp_connects_in_flight
with _mcp_sessions_lock:
generation = _mcp_close_generation(url, headers)
_mcp_connects_in_flight += 1
try:
yield generation
finally:
with _mcp_sessions_lock:
_mcp_connects_in_flight -= 1
def _get_session(
url: str,
headers: Optional[dict],
scope: Optional[str],
deadline,
cancel_event,
config_check,
use_oauth: bool = False,
) -> tuple[_McpSession, float]:
"""Key-lock wait and connect share one absolute deadline so slow startups cannot stack timeouts; only the borrower may act on its idle gap."""
global _mcp_reaper_started
key = _session_key(url, headers, scope)
with _mcp_sessions_lock:
session, idle_for = _checkout_session(key)
if session is not None:
return session, idle_for
key_lock = _borrow_key_lock(key)
try:
# Poll so a same-scope call can be cancelled while queued behind a slow startup.
remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
# Key-lock wait is bounded like the connect behind it, so HTTP is not cut off at the stdio cap.
window = _connect_window(url, remaining)
lock_deadline = None if window is None else time.monotonic() + window
while not key_lock.lock.acquire(timeout = 0.05):
if cancel_event is not None and cancel_event.is_set():
raise _MCPCancelled
if lock_deadline is not None and time.monotonic() >= lock_deadline:
raise _ConnectTimeout(window)
try:
stale = None
with _mcp_sessions_lock:
session, idle_for = _checkout_session(key)
if session is not None:
return session, idle_for
if key in _mcp_sessions:
stale = _mcp_sessions.pop(key)
if stale is not None:
_retire_session(stale)
with _connect_slot(url, headers) as generation:
session = _McpSession(url, headers, use_oauth)
try:
session.connect(
None if deadline is None else max(0.0, deadline - time.monotonic()),
cancel_event,
)
except Exception:
session.close()
raise
if config_check is not None:
try:
current = bool(config_check())
except Exception: # noqa: BLE001
current = False
if not current:
session.close()
raise RuntimeError("MCP server was updated or removed while connecting")
evicted: list = []
with _mcp_sessions_lock:
closed_while_connecting = _mcp_close_generation(url, headers) != generation
if not closed_while_connecting:
session.in_flight = 1
evicted = _evict_lru_locked() # bound the cache (LRU idle)
_mcp_sessions[key] = session
if not _mcp_reaper_started:
_mcp_reaper_started = True
threading.Thread(
target = _session_reaper, name = "mcp-session-reaper", daemon = True
).start()
atexit.register(close_mcp_sessions, all_accounts = True)
for victim in evicted:
logger.info("Evicting LRU idle MCP session: %s", _session_log_id(victim.url))
if evicted:
# Detached: an unresponsive close would eat this caller's tool-call deadline.
_close_detached(evicted)
if closed_while_connecting:
session.close()
raise RuntimeError("MCP server was updated or removed while connecting")
return session, -1.0
finally:
key_lock.lock.release()
finally:
_return_key_lock(key, key_lock)
def _release_session(session: _McpSession, defer_close: bool = False) -> None:
victims: list = []
with _mcp_sessions_lock:
session.in_flight = max(0, session.in_flight - 1)
session.last_used = time.monotonic()
close_now = session.defunct and session.in_flight == 0
# Re-enforce the cap once a burst idles; never evict the session just used; the cap is per account, so a call never closes sessions of another account.
account_id = getattr(session, "account_id", None) or current_account_id()
mine = {
k: s
for k, s in _mcp_sessions.items()
if (k[3] if len(k) > 3 else OWNER_ACCOUNT_ID) == account_id
}
while len(mine) > _MAX_SESSIONS:
idle = [
(s.last_used, k) for k, s in mine.items() if s.in_flight == 0 and s is not session
]
if not idle:
break
_, oldest = min(idle, key = lambda item: item[0])
victims.append(_mcp_sessions.pop(oldest))
mine.pop(oldest)
_discard_key_lock(oldest)
if close_now and defer_close:
# Close off the request path: a discarded transport's close runs long.
victims.append(session)
elif close_now:
session.close()
if victims:
_close_detached(victims)
def _retire_session(session: _McpSession) -> None:
"""Close a discarded session, but only once no other borrower is mid-call on it: overlapping
same-scope calls share one client, and one call's timeout must not kill another's in-flight
request. The last borrower's _release_session() performs the deferred close."""
with _mcp_sessions_lock:
session.defunct = True
busy = session.in_flight > 0
if not busy:
session.close()
def _drop_session(key: tuple, session: _McpSession) -> None:
with _mcp_sessions_lock:
if _mcp_sessions.get(key) is session:
_mcp_sessions.pop(key)
_discard_key_lock(key)
_retire_session(session)
def _evict_lru_locked() -> list:
"""Caller holds _mcp_sessions_lock; returns idle LRU victims to close outside it; if every
session is busy the cache may overshoot the cap rather than kill an in-flight call"""
victims: list = []
if len(_mcp_sessions) < _MAX_SESSIONS:
return victims
account_id = current_account_id()
candidates = {
key: session
for key, session in _mcp_sessions.items()
if (key[3] if len(key) > 3 else OWNER_ACCOUNT_ID) == account_id
}
while len(candidates) >= _MAX_SESSIONS:
idle = [(s.last_used, k) for k, s in candidates.items() if s.in_flight == 0]
if not idle:
break
_, oldest = min(idle, key = lambda item: item[0])
victims.append(_mcp_sessions.pop(oldest))
candidates.pop(oldest)
_discard_key_lock(oldest)
return victims
def close_mcp_sessions(
url: Optional[str] = None,
headers = _ANY_HEADERS,
*,
all_accounts: bool = False,
) -> None:
global _mcp_close_all_gen
hk = None if headers is _ANY_HEADERS else _headers_key(headers)
account_id = current_account_id()
with _mcp_sessions_lock:
keys = [
k
for k in _mcp_sessions
if (url is None or k[0] == url)
and (hk is None or k[1] == hk)
and (all_accounts or (k[3] if len(k) > 3 else OWNER_ACCOUNT_ID) == account_id)
]
sessions = [_mcp_sessions.pop(k) for k in keys]
for key in keys:
_discard_key_lock(key)
if sessions or _mcp_connects_in_flight:
if url is None:
if all_accounts:
_mcp_close_all_gen += 1
else:
_mcp_account_close_gen[account_id] = (
_mcp_account_close_gen.get(account_id, 0) + 1
)
elif hk is None:
uk = _url_close_key(url)
_mcp_url_close_gen[uk] = _mcp_url_close_gen.get(uk, 0) + 1
else:
cfg = _cfg_close_key(url, headers)
_mcp_cfg_close_gen[cfg] = _mcp_cfg_close_gen.get(cfg, 0) + 1
pending, worker = _drain_cleanup_queue()
_close_all(sessions + pending)
if worker is not None and worker is not threading.current_thread():
# Draining does not recall a popped session, so the join waits for that one close and no longer.
worker.join(_SESSION_CLOSE_TIMEOUT + 5.0)
def _close_all(sessions: list) -> None:
"""Closes at most _MAX_CLOSE_THREADS at once; serial closes could stall a request for minutes."""
if not sessions:
return
if len(sessions) == 1:
sessions[0].close()
return
pending = list(sessions)
pending_lock = threading.Lock()
def _drain() -> None:
while True:
with pending_lock:
if not pending:
return
session = pending.pop()
_close_quietly(session)
# Bare threads: executors are shut down before atexit callbacks, so submitting there raises.
width = min(len(pending), _MAX_CLOSE_THREADS)
threads = [threading.Thread(target = _drain, name = "mcp-close", daemon = True) for _ in range(width)]
for thread in threads:
thread.start()
# Each worker closes several sessions in turn, so the join budget scales with the rounds.
rounds = -(-len(sessions) // width)
for thread in threads:
thread.join(rounds * (_SESSION_CLOSE_TIMEOUT + 5.0))
def _close_detached(sessions: list) -> None:
"""One worker, not a thread per session, so closes cannot spawn unbounded threads; past _MAX_PENDING_CLOSES the caller closes the overflow as backpressure."""
global _mcp_cleanup_worker
if not sessions:
return
with _mcp_cleanup_lock:
room = max(0, _MAX_PENDING_CLOSES - len(_mcp_cleanup_queue))
_mcp_cleanup_queue.extend(sessions[:room])
overflow = sessions[room:]
if _mcp_cleanup_queue and _mcp_cleanup_worker is None:
_mcp_cleanup_worker = threading.Thread(
target = _cleanup_worker, name = "mcp-cleanup", daemon = True
)
_mcp_cleanup_worker.start()
_close_all(overflow)
def _cleanup_worker() -> None:
global _mcp_cleanup_worker
while True:
with _mcp_cleanup_lock:
if not _mcp_cleanup_queue:
_mcp_cleanup_worker = None # _close_detached starts the next one
return
session = _mcp_cleanup_queue.pop(0)
_close_quietly(session)
def _drain_cleanup_queue() -> tuple[list, Optional[threading.Thread]]:
"""Takes back unstarted cleanups and the worker so a caller can wait out the active close."""
with _mcp_cleanup_lock:
pending = list(_mcp_cleanup_queue)
_mcp_cleanup_queue.clear()
return pending, _mcp_cleanup_worker
def _close_quietly(session) -> None:
try:
session.close()
except Exception: # noqa: BLE001
logger.exception("Closing a discarded MCP session failed")
# Legacy alias kept for callers of the old name.
close_stdio_sessions = close_mcp_sessions
def _reset_after_fork() -> None:
"""Only the forking thread survives a fork, so inherited session loops are dead; close nothing."""
global _mcp_reaper_started, _mcp_connects_in_flight, _mcp_sessions_lock
global _mcp_cleanup_lock, _mcp_cleanup_worker
# Replaced: a lock held at fork belongs to a thread that does not exist in the child.
_mcp_sessions_lock = threading.Lock()
_mcp_sessions.clear()
_mcp_key_locks.clear()
_mcp_connects_in_flight = 0
_mcp_reaper_started = False
# The cleanup worker did not survive the fork either, and its queue holds the parent's sessions.
_mcp_cleanup_lock = threading.Lock()
_mcp_cleanup_queue.clear()
_mcp_cleanup_worker = None
if hasattr(os, "register_at_fork"):
os.register_at_fork(after_in_child = _reset_after_fork)
def _reap_idle_sessions(now: Optional[float] = None) -> None:
now = time.monotonic() if now is None else now
with _mcp_sessions_lock:
expired = [
key
for key, session in _mcp_sessions.items()
if session.in_flight == 0
and (now - session.last_used >= _SESSION_IDLE_TTL or session.abandoned_overdue(now))
]
sessions = [_mcp_sessions.pop(key) for key in expired]
for key in expired:
_discard_key_lock(key)
for session in sessions:
logger.info("Closing idle MCP session: %s", _session_log_id(session.url))
session.close()
def _session_reaper() -> None:
while True:
time.sleep(_SESSION_REAP_INTERVAL)
try:
_reap_idle_sessions()
except Exception as exc: # noqa: BLE001
logger.debug("MCP session reaper iteration failed: %s", exc)
MCP_RESOURCE_TOOL = "read_resource"
MAX_MCP_RESOURCES = 200
class McpToolList(list):
"""Tools plus the resources listed on the same connection."""
resources: Optional[list[dict]] = None
def _capabilities(client) -> Any:
# initialize_result stays None on a modern connection, which has no initialize handshake.
return getattr(client, "server_capabilities", None)
async def _list_resources(client) -> Optional[list[dict]]:
capabilities = _capabilities(client)
if capabilities is not None and getattr(capabilities, "resources", None) is None:
return None
listed, cursors = [], set()
cursor = None
try:
while len(listed) < MAX_MCP_RESOURCES:
page = await client.list_resources_mcp(cursor = cursor)
listed.extend(getattr(page, "resources", None) or ())
cursor = getattr(page, "next_cursor", None)
# A repeated cursor would loop forever.
if not cursor or cursor in cursors:
break
cursors.add(cursor)
except Exception as exc: # noqa: BLE001 - resources are optional, the tools still load
logger.debug("MCP resources/list failed: %s", exc)
if not listed:
return None
resources = []
for resource in listed:
uri = str(getattr(resource, "uri", "") or "")
# MCP Apps templates are for the host's widgets, not the model.
if not uri or uri.startswith(UI_RESOURCE_SCHEME):
continue
audience = getattr(getattr(resource, "annotations", None), "audience", None)
if audience and "assistant" not in audience:
continue
fields = {
"name": getattr(resource, "name", None),
"description": getattr(resource, "description", None),
"mimeType": _resource_mime(resource),
}
resources.append(
{"uri": uri, **{k: v for k, v in fields.items() if isinstance(v, str) and v}}
)
return resources[:MAX_MCP_RESOURCES] or None
async def list_tools_async(
url: str,
headers: Optional[dict] = None,
timeout: float = 5.0,
use_oauth: bool = False,
**oauth,
) -> list[dict]:
listed: list = []
async def _fetch() -> list[dict]:
async with _client(url, headers, use_oauth, **oauth) as client:
try:
raw_tools = await client.list_tools()
except Exception:
# A resource-only server need not answer tools/list.
capabilities = _capabilities(client)
if (
capabilities is None
or getattr(capabilities, "tools", None) is not None
or getattr(capabilities, "resources", None) is None
):
raise
raw_tools = []
tools = McpToolList(t.model_dump(exclude_none = True) for t in raw_tools)
listed.append(tools)
tools.resources = await _list_resources(client)
return tools
try:
return await asyncio.wait_for(_fetch(), timeout = timeout)
except asyncio.TimeoutError:
# A slow resources/list must not cost the server its tools.
if listed:
return listed[0]
raise
# Probe only on cache miss, off the chat send's critical path. Successful probes cached forever.
_tool_cache: dict[str | tuple[str, str], list[dict]] = {}
# Failed server's re-probe cooloff (monotonic time); cleared on a good probe or eviction.
_probe_cooloff_until: dict[str | tuple[str, str], float] = {}
# Coordinate off-loop token-count snapshots with row and schema-cache mutations.
_mcp_server_snapshot_locks: WeakKeyDictionary[asyncio.AbstractEventLoop, asyncio.Lock] = (
WeakKeyDictionary()
)
def mcp_server_snapshot_guard() -> asyncio.Lock:
loop = asyncio.get_running_loop()
return _mcp_server_snapshot_locks.setdefault(loop, asyncio.Lock())
def serialize_mcp_server_mutation(handler):
"""Run an MCP mutation from validation through row/cache commit as one snapshot."""
@wraps(handler)
async def _serialized(*args, **kwargs):
async with mcp_server_snapshot_guard():
return await handler(*args, **kwargs)
return _serialized
# Shared by the update route's eviction and the mid-probe guard so they can't drift.
TOOL_CACHE_INVALIDATING_FIELDS = frozenset(
{"url", "headers_json", "use_oauth", "oauth_client_id", "oauth_client_secret", "is_enabled"}
)
def get_cached_tools(server_id: str) -> Optional[list[dict]]:
return _tool_cache.get(_account_key(server_id))
def get_cached_resources(server_id: str) -> Optional[list[dict]]:
return getattr(_tool_cache.get(_account_key(server_id)), "resources", None)
def cache_tools(server_id: str, tools: list[dict]) -> None:
_tool_cache[_account_key(server_id)] = tools
_probe_cooloff_until.pop(_account_key(server_id), None)
def record_probe_failure(server_id: str, use_oauth: bool = False) -> None:
cooloff = OAUTH_FAILED_PROBE_COOLOFF_SECONDS if use_oauth else FAILED_PROBE_COOLOFF_SECONDS
_probe_cooloff_until[_account_key(server_id)] = time.monotonic() + cooloff
def in_failure_cooloff(server_id: str) -> bool:
return _probe_cooloff_until.get(_account_key(server_id), 0.0) > time.monotonic()
def invalidate_tool_cache(server_id: Optional[str] = None) -> None:
"""Evict one server's cached tools, or every entry when server_id is None."""
if server_id is None:
account_id = current_account_id()
for cache in (_tool_cache, _probe_cooloff_until):
for key in list(cache):
owner = key[0] if isinstance(key, tuple) else OWNER_ACCOUNT_ID
if owner == account_id:
cache.pop(key, None)
else:
_tool_cache.pop(_account_key(server_id), None)
_probe_cooloff_until.pop(_account_key(server_id), None)
UI_RESOURCE_SCHEME = "ui://"
MAX_UI_RESOURCE_CHARS = 5_000_000
def _ui_meta_field(tool: Any, field: str):
"""`ui.<field>`, else the flat `ui/<field>`, from the SDK's `meta` or the wire `_meta`."""
metas = [tool.get(k) for k in ("meta", "_meta")] if isinstance(tool, dict) else []
metas = [m for m in metas if isinstance(m, dict)]
for ui in (m.get("ui") for m in metas):
if isinstance(ui, dict) and ui.get(field) is not None:
return ui[field]
return next((m[f"ui/{field}"] for m in metas if m.get(f"ui/{field}") is not None), None)
def tool_ui_resource_uri(tool: Any) -> Optional[str]:
"""Only ui:// is honoured: the host fetches this URI."""
uri = _ui_meta_field(tool, "resourceUri")
uri = uri.strip() if isinstance(uri, str) else ""
return (
uri if uri.startswith(UI_RESOURCE_SCHEME) and len(uri) > len(UI_RESOURCE_SCHEME) else None
)
def tool_visible_to(tool: Any, audience: str) -> bool:
"""`audience` is "model" or "app"; an undeclared visibility means both."""
visibility = _ui_meta_field(tool, "visibility")
return audience in visibility if isinstance(visibility, (list, tuple)) else True
MCP_IMAGES_SENTINEL = mcp_images.SENTINEL
MAX_IMAGE_PAYLOAD_CHARS = 12_000_000
# Emitted BEFORE the image envelope, whose parse reads to end of string.
MCP_UI_SENTINEL = "__MCP_UI__:"
MAX_UI_STRUCTURED_CHARS = 1_000_000
def _json_within(value: Any, limit: int) -> Optional[str]:
try:
line = json.dumps(value)
except (TypeError, ValueError, RecursionError):
return None
return line if len(line) <= limit else None
def _ui_envelope(result: Any, ui_resource_uri: str, seed: list) -> str:
payload: dict = {"resourceUri": ui_resource_uri}
meta = getattr(result, "meta", None)
if isinstance(meta, dict) and meta:
payload["_meta"] = meta
structured = getattr(result, "structured_content", None)
if structured is not None:
payload["structuredContent"] = structured
if seed:
payload["content"] = [
_seeded_image_block(b, m) if m else _content_block_json(b) for b, m in seed
]
line = _json_within(payload, MAX_UI_STRUCTURED_CHARS)
if line is None:
# Shed structuredContent, then content, then _meta: the view still gets its template.
reduced = {"resourceUri": ui_resource_uri, "structuredContentOmitted": True}
keys = [k for k in ("content", "_meta") if k in payload]
for kept in (keys, keys[:1], keys[1:]):
line = _json_within(
{**reduced, **{k: payload[k] for k in kept}}, MAX_UI_STRUCTURED_CHARS
)
if line:
break
else:
line = json.dumps(reduced)
return "\n" + MCP_UI_SENTINEL + line
def _is_ui_envelope_line(line: str) -> bool:
if not line.startswith(MCP_UI_SENTINEL):
return False
try:
payload = json.loads(line[len(MCP_UI_SENTINEL) :])
except (ValueError, RecursionError):
return False
return isinstance(payload, dict) and isinstance(payload.get("resourceUri"), str)
def _drop_forged_ui_sentinels(body: str) -> str:
"""Readers take the last marker, so a tool-written one could summon a widget with forged seed text."""
if MCP_UI_SENTINEL not in body:
return body
return "\n".join(line for line in body.split("\n") if not _is_ui_envelope_line(line))
def _block_text(block: Any) -> Optional[str]:
text = getattr(block, "text", None)
if text:
return str(text)
resource = getattr(block, "resource", None)
if resource is not None:
text = getattr(resource, "text", None)
return str(text) if text else None
return None
def _block_link(block: Any) -> Optional[str]:
# keep host-generated link text from suppressing structured_content
uri = getattr(block, "uri", None)
if uri and getattr(block, "type", None) == "resource_link":
name = getattr(block, "name", None)
return f"[resource: {name} <{uri}>]" if name else f"[resource: <{uri}>]"
return None
# fastmcp File(data=..., format=...) labels payloads as application/<format>
_IMAGE_SUBTYPES = {
"apng": "image/apng",
"png": "image/png",
"jpeg": "image/jpeg",
"jpg": "image/jpeg",
"gif": "image/gif",
"webp": "image/webp",
"bmp": "image/bmp",
"avif": "image/avif",
"tif": "image/tiff",
"tiff": "image/tiff",
"ico": "image/vnd.microsoft.icon",
"svg": "image/svg+xml",
"svg+xml": "image/svg+xml",
}
# Interpolated into data: URLs by tool-fallback.tsx; RFC 9110 token subtype, minus '*'.
_MEDIA_TYPE = re.compile(r"^image/[a-z0-9][a-z0-9!#$%&'^_`|~.+-]*$")
def _uri_mime(uri: Any) -> Optional[str]:
"""Drops query and fragment so every Python guesses the same type; the scheme stays for data: URIs."""
split = urlsplit(str(uri))
cleaned = urlunsplit((split.scheme, split.netloc if split.path else "", split.path, "", ""))
return mimetypes.guess_type(cleaned, strict = False)[0]
def _image_mime(mime: Any) -> Optional[str]:
if not isinstance(mime, str):
return None
# media type names are case-insensitive; data urls need only the essence
essence = mime.partition(";")[0].strip().lower()
if essence.startswith("image/"):
resolved = essence
else:
subtype = essence[len("application/") :] if essence.startswith("application/") else ""
resolved = _IMAGE_SUBTYPES.get(subtype) or _uri_mime(f"file:///image.{subtype}")
# Windows registry returns image/JXL, so lowercase again.
resolved = resolved.lower() if resolved else ""
return resolved if _MEDIA_TYPE.match(resolved) else None
def _resource_mime(obj: Any) -> Any:
# mcp 2.x exposes mime_type; mimeType is only a constructor alias there
return obj.mime_type if hasattr(obj, "mime_type") else getattr(obj, "mimeType", None)
def _block_image(block: Any) -> Optional[tuple[str, str]]:
# embedded resources keep binary data on resource.blob
data = getattr(block, "data", None)
mime = _resource_mime(block)
if not data:
resource = getattr(block, "resource", None)
if resource is None:
return None
data = getattr(resource, "blob", None)
mime = _resource_mime(resource)
if not mime:
uri = getattr(resource, "uri", None)
mime = _uri_mime(uri) if uri else None
mime = _image_mime(mime)
if data and mime:
return str(data), mime
return None
def _block_attachment(block: Any) -> Optional[tuple[str, str]]:
# presence, not truthiness: a zero-byte file arrives as ""
data = getattr(block, "data", None)
if data is not None:
kind = getattr(block, "type", "binary")
mime = _resource_mime(block)
uri = None
else:
resource = getattr(block, "resource", None)
data = getattr(resource, "blob", None) if resource is not None else None
if data is None:
return None
kind = "file"
mime = _resource_mime(resource)
uri = getattr(resource, "uri", None)
label = f"{kind} attachment"
if mime:
label += f" ({mime})"
if uri and not str(uri).lower().startswith("data:"):
label += f" <{uri}>"
return f"{label} not shown to the model", str(data)
_MIRRORED = object()
# fields MCP defines on image/audio and embedded resource blocks; anything else is the tool's own
_MEDIA_FIELDS = frozenset({"type", "data", "mimeType", "mime_type", "annotations", "_meta"})
_RESOURCE_BLOCK_FIELDS = frozenset({"type", "resource", "annotations", "_meta"})
_RESOURCE_FIELDS = frozenset({"uri", "blob", "mimeType", "mime_type", "_meta"})
def _is_payload(value: Any, payloads: set[str]) -> bool:
return isinstance(value, str) and value in payloads
def _mirrored_extras(value: dict, payloads: set[str]) -> Optional[dict]:
# the tool's own fields on a content block copied from result.content; None if it is not one
kind = value.get("type")
if kind in ("image", "audio") and _is_payload(value.get("data"), payloads):
return {k: v for k, v in value.items() if k not in _MEDIA_FIELDS}
resource = value.get("resource")
if (
kind == "resource"
and isinstance(resource, dict)
and _is_payload(resource.get("blob"), payloads)
):
extras = {k: v for k, v in value.items() if k not in _RESOURCE_BLOCK_FIELDS}
inner = {k: v for k, v in resource.items() if k not in _RESOURCE_FIELDS}
if inner:
extras["resource"] = inner
return extras
return None
def _strip_payloads(value: Any, payloads: set[str]) -> Any:
# drop mirrored payloads and the MCP fields of the blocks carrying them, then containers left empty
if isinstance(value, str):
return _MIRRORED if value in payloads else value
if isinstance(value, dict):
extras = _mirrored_extras(value, payloads)
if extras is not None:
if not extras:
return _MIRRORED
value = extras
kept = {}
for key, item in value.items():
item = _strip_payloads(item, payloads)
if item is not _MIRRORED:
kept[key] = item
elif isinstance(value, (list, tuple)):
kept = [
s for s in (_strip_payloads(item, payloads) for item in value) if s is not _MIRRORED
]
else:
return value
return _MIRRORED if value and not kept else kept
# The frontend refills bytes positionally: `data` on an image block, `resource.blob` on an embedded one.
def _seeded_image_block(block: Any, mime: str) -> dict:
out = {k: v for k, v in _content_block_json(block).items() if k != "data"}
if isinstance(out.get("resource"), dict):
out["resource"] = {k: v for k, v in out["resource"].items() if k != "blob"}
return out
return {**out, "type": "image", "mimeType": mime}
def _flatten_result(result: Any, ui_resource_uri: Optional[str] = None) -> str:
parts = []
images = []
seed = []
unshown = []
payloads = set()
omitted = 0
has_text = False
budget = MAX_IMAGE_PAYLOAD_CHARS
for block in getattr(result, "content", None) or []:
text = _block_text(block)
if text:
parts.append(text)
has_text = True
seed.append((block, None))
continue
link = _block_link(block)
if link:
parts.append(link)
seed.append((block, None))
continue
image = _block_image(block)
if image is not None:
data, mime = image
payloads.add(data)
if len(data) > budget:
omitted += 1
continue
budget -= len(data)
images.append({"data": data, "mimeType": mime})
seed.append((block, mime))
continue
seed.append((block, None))
attachment = _block_attachment(block)
if attachment is not None:
note, data = attachment
unshown.append(note)
if data:
payloads.add(data)
body = "\n".join(parts)
# the filesystem server mirrors binary blocks in structured_content; keep everything else
structured = None if has_text else getattr(result, "structured_content", None)
if structured is not None and payloads:
structured = _strip_payloads(structured, payloads)
if structured is not None and structured is not _MIRRORED:
body = f"{structured}\n{body}" if body else str(structured)
if images or omitted or unshown:
notes = []
if images:
n = len(images)
notes.append(f"{n} image{'s' if n > 1 else ''} returned")
if omitted:
notes.append(f"{omitted} image{'s' if omitted > 1 else ''} omitted (too large)")
notes.extend(unshown)
note = f"[{'; '.join(notes)}]"
body = f"{body}\n{note}" if body else note
if getattr(result, "is_error", False):
# "Error: " prefix triggers tool_call_parser's TOOL_ERROR_PREFIXES nudge.
body = f"Error: {body}" if body else "Error: tool returned no content"
body = _drop_forged_ui_sentinels(body)
if ui_resource_uri and not getattr(result, "is_error", False):
body += _ui_envelope(result, ui_resource_uri, seed)
if images:
body += "\n" + MCP_IMAGES_SENTINEL + json.dumps(images)
return body
def _unwind_budget(unwind_timeout: float, timeout: Optional[float], elapsed: float) -> float:
"""A cancelled call's unwind wait is the caller's leftover window, never past a deadline."""
if not unwind_timeout:
return 0.0
if timeout is None:
return unwind_timeout
return min(unwind_timeout, max(0.0, timeout - elapsed))
async def _race_tool_call(
call_coro,
timeout: Optional[float],
cancel_event,
unwind_timeout: float = 0.0,
) -> Any:
"""Polls cancel_event alongside the call, so a /cancel interrupts a read already in flight."""
async def _watch_cancel() -> None:
while cancel_event is not None and not cancel_event.is_set():
await asyncio.sleep(0.05)
if cancel_event is not None and cancel_event.is_set():
call_coro.close()
raise _MCPCancelled
started = time.monotonic()
call_task = asyncio.create_task(call_coro)
if cancel_event is None:
return await asyncio.wait_for(call_task, timeout = timeout)
watch_task = asyncio.create_task(_watch_cancel())
try:
done, pending = await asyncio.wait(
{call_task, watch_task},
timeout = timeout,
return_when = asyncio.FIRST_COMPLETED,
)
finally:
for t in (call_task, watch_task):
if not t.done():
t.cancel()
# Cancelled calls unwind within the caller's remaining budget, or the session is left dirty.
left = _unwind_budget(unwind_timeout, timeout, time.monotonic() - started)
if left:
await asyncio.wait({call_task, watch_task}, timeout = left)
if not done:
raise asyncio.TimeoutError
if call_task in done:
return call_task.result()
raise _MCPCancelled
async def _enqueued(tracker: _PostTracker, slot: _PostSlot, call) -> Any:
tracker.enqueue(slot)
return await call
def _call_session_tool(
url: str,
headers: Optional[dict],
name: str,
args: dict,
timeout,
cancel_event,
scope: Optional[str],
config_check,
use_oauth: bool = False,
dispatch = None,
rpc: Optional[tuple] = None,
) -> Any:
if cancel_event is not None and cancel_event.is_set():
raise _MCPCancelled
if dispatch is None:
rpc = ("tools/call", name)
# One deadline covers the key-lock wait, connect, call-lock wait, and the call itself, matching the one-shot path
# where the caller's timeout wrapped connect plus call in a single window.
deadline = None if timeout is None else time.monotonic() + timeout
def _remaining() -> Optional[float]:
return None if deadline is None else max(0.0, deadline - time.monotonic())
# No session id: use an ephemeral key so no state leaks across requests.
def _config_ok() -> bool:
if config_check is None:
return True
try:
return bool(config_check())
except Exception: # noqa: BLE001
return False
ephemeral = not scope
if ephemeral:
scope = f"request-{uuid.uuid4().hex}"
key = _session_key(url, headers, scope)
# Attempt 0 may reconnect once if the cached session died before dispatch; attempt 1 is fresh.
for attempt in (0, 1):
session, idle_for = _get_session(
url, headers, scope, deadline, cancel_event, config_check, use_oauth
)
locked = False
try:
# Serialize stdio (stateful byte stream); HTTP multiplexes by request id.
if session.serialize_calls:
while not session.call_lock.acquire(timeout = 0.05):
if cancel_event is not None and cancel_event.is_set():
raise _MCPCancelled
rem = _remaining()
if rem is not None and rem <= 0:
raise asyncio.TimeoutError
locked = True
except BaseException:
# Never touched the transport: keep the session for its borrower.
_release_session(session)
if ephemeral:
_drop_session(key, session)
raise
discard_session = ephemeral
slot = None
retry = False
try:
# Re-check after waiting on the call lock: session may be retired, invalidated or dead.
if session.closed.is_set():
# Intentional close (server update/delete/shutdown): don't retry on stale config.
discard_session = True
raise RuntimeError("MCP server was updated or removed during the call")
elif session.defunct:
# A same-scope timeout retired this session; switch to a fresh one rather than reuse it.
discard_session = True
if attempt == 0:
retry = True
else:
raise RuntimeError("MCP server session was retired during the call")
elif not _config_ok():
discard_session = True
raise RuntimeError("MCP server was updated or removed during the call")
elif _transport_dead(session):
# Dead BEFORE dispatch: no request was sent, so reconnect + retry.
discard_session = True
if attempt == 0:
retry = True
else:
raise RuntimeError("MCP server connection is not available")
elif session.abandoned_overdue():
# A probe would prove the server is up, not that the abandoned POSTs closed.
discard_session = True
if attempt == 0:
retry = True
else:
raise RuntimeError("MCP server session was retired during the call")
elif (
session.dirty or _needs_idle_recheck(session, idle_for, _remaining())
) and not _session_responsive(
session, _remaining(), cancel_event, timeout_is_fatal = session.dirty
):
# Dirty or idle-HTTP sessions may be dead; reconnect BEFORE dispatch.
discard_session = True
if attempt == 0:
retry = True
else:
raise RuntimeError("MCP server is not responding")
else:
rem = _remaining()
slot = _PostSlot(rpc)
# raise_on_error=False for the same reason as the one-shot path.
coro = _race_tool_call(
_enqueued(
session.posts,
slot,
dispatch(session.client)
if dispatch is not None
else session.client.call_tool(name, args, raise_on_error = False),
),
rem,
cancel_event,
# Only a cached session is worth waiting on.
0.0 if ephemeral else _CANCEL_UNWIND_TIMEOUT,
)
out = session.run(coro, rem)
# A completed round trip proves the transport better than a probe, so it resets the idle clock.
session.proved_at = time.monotonic()
return out
except (_MCPCancelled, asyncio.TimeoutError):
# Keep the session so Stop doesn't destroy server state; reuse is gated on a live probe.
session.dirty = True
if not ephemeral and slot is not None:
session.note_abandoned(slot)
raise
except _SessionWedged:
discard_session = True
raise asyncio.TimeoutError
except _SessionClosed:
# close_mcp_sessions() shut this session mid-call, so do not retry against the stale config.
discard_session = True
raise RuntimeError("MCP server was updated or removed during the call")
except Exception as exc:
if session.closed.is_set():
# Intentional close may look like a transport error or AttributeError; do not treat as crash
discard_session = True
raise RuntimeError("MCP server was updated or removed during the call")
if _is_session_terminated(exc):
# A 404 means the server never processed the request, so reconnect and replay once.
discard_session = True
retry = attempt == 0
# Protocol error = server alive, keep session. Transport error: evict but DO NOT replay.
elif _is_protocol_error(exc):
# A protocol error means the server replied, so keep the session but probe it before the next call.
session.dirty = True
elif not _is_tool_error(exc):
discard_session = True
if not retry:
raise
finally:
if slot is not None:
session.posts.settle(slot, abandoned = False)
# Drop the broken session from the cache before its borrow is released, so no caller
# reuses it.
if discard_session:
_drop_session(key, session)
_release_session(session, defer_close = not ephemeral)
if locked:
session.call_lock.release()
if not retry:
break
raise RuntimeError("unreachable")
def call_tool_sync(
url: str,
headers: Optional[dict],
name: str,
args: dict,
timeout: Optional[float] = 300.0,
use_oauth: bool = False,
cancel_event = None,
scope: Optional[str] = None,
config_check = None,
ui_resource_uri: Optional[str] = None,
**oauth,
) -> str:
"""Never raises: failures return as Error strings; OAuth or scope-less HTTP connects once per call."""
if is_studio_tools(url):
if config_check is not None and not config_check():
return f"Error: MCP tool '{name}' failed: MCP server was updated or removed"
from core.inference import studio_tools_mcp
return studio_tools_mcp.call(
name,
args,
timeout = timeout,
cancel_event = cancel_event,
ui_resource_uri = ui_resource_uri,
config_check = config_check,
)
async def _one_shot() -> Any:
async with _client(url, headers, use_oauth, **oauth) as client:
# Connecting (OAuth included) can outlast an edit or delete of the server row.
if config_check is not None and not config_check():
raise RuntimeError("MCP server was updated or removed while connecting")
# raise_on_error=False so an is_error result keeps its image content.
return await client.call_tool(name, args, raise_on_error = False)
try:
if is_stdio(url) or (scope and not use_oauth):
result = _call_session_tool(
url, headers, name, args, timeout, cancel_event, scope, config_check, use_oauth
)
else:
result = asyncio.run(_race_tool_call(_one_shot(), timeout, cancel_event))
except _MCPCancelled:
return f"Error: MCP tool '{name}' cancelled"
except _ConnectTimeout as exc:
# Report the window that expired: for stdio the cold-start cap, not the larger caller timeout.
suffix = f" after {round(exc.window, 1):g}s" if exc.window is not None else ""
return f"Error: MCP tool '{name}' timed out connecting{suffix}"
except asyncio.TimeoutError:
suffix = f" after {timeout:g}s" if timeout is not None else ""
return f"Error: MCP tool '{name}' timed out{suffix}"
except Exception as exc:
logger.exception("MCP call_tool failed for %s: %s", name, exc)
return f"Error: MCP tool '{name}' failed: {exc}"
return _flatten_result(result, ui_resource_uri)
MAX_UI_TOOL_RESULT_CHARS = 4_000_000
def _content_block_json(block: Any) -> dict:
dump = getattr(block, "model_dump", None)
if callable(dump):
try:
# by_alias, or the SDK's `meta` reaches the widget instead of `_meta`.
return dump(mode = "json", exclude_none = True, by_alias = True)
except Exception: # noqa: BLE001
pass
out = {"type": getattr(block, "type", "text")}
for field in ("text", "data", "mimeType", "uri", "name"):
value = getattr(block, field, None)
if value is not None:
out[field] = value if isinstance(value, (str, int, float, bool)) else str(value)
return out
def _structured_result(result: Any) -> dict:
out: dict = {
"content": [_content_block_json(b) for b in getattr(result, "content", None) or []],
"is_error": bool(getattr(result, "is_error", False)),
}
if getattr(result, "structured_content", None) is not None:
out["structured_content"] = result.structured_content
meta = getattr(result, "meta", None)
if isinstance(meta, dict) and meta:
out["meta"] = meta
if _json_within(out, MAX_UI_TOOL_RESULT_CHARS) is None:
raise ValueError(
f"tool result is not JSON-serialisable or over {MAX_UI_TOOL_RESULT_CHARS} chars"
)
return out
def _ui_request_sync(
url,
headers,
label,
dispatch,
*,
timeout,
use_oauth = False,
cancel_event = None,
scope = None,
config_check = None,
rpc = None,
**oauth,
) -> Any:
"""``dispatch(client)`` on the transport call_tool_sync picks for this scope; ``rpc`` = (method, name or URI)."""
async def _one_shot() -> Any:
# As the session branch: an edit during discovery must not reach the old endpoint.
if config_check is not None and not config_check():
raise RuntimeError("MCP server was updated or removed during the call")
async with _client(url, headers, use_oauth, **oauth) as client:
# Connecting (OAuth included) can outlast an edit, as in call_tool_sync.
if config_check is not None and not config_check():
raise RuntimeError("MCP server was updated or removed while connecting")
return await dispatch(client)
session_args = (url, headers, label, {}, timeout, cancel_event, scope, config_check, use_oauth)
try:
if is_stdio(url) or (scope and not use_oauth):
return _call_session_tool(*session_args, dispatch = dispatch, rpc = rpc)
return asyncio.run(_race_tool_call(_one_shot(), timeout, cancel_event))
except _MCPCancelled as exc:
raise TimeoutError(f"{label} was cancelled") from exc
def call_tool_structured_sync(
url: str, headers: Optional[dict], name: str, args: dict, **kw
) -> dict:
dispatch = lambda client: client.call_tool(name, args, raise_on_error = False) # noqa: E731
label = f"MCP tool '{name}'"
return _structured_result(
_ui_request_sync(url, headers, label, dispatch, rpc = ("tools/call", name), **kw)
)
def read_resource_sync(url: str, headers: Optional[dict], uri: str, **kw) -> dict:
dispatch = lambda client: client.read_resource(uri) # noqa: E731
return _resource_contents(
_ui_request_sync(
url, headers, f"MCP resource '{uri}'", dispatch, rpc = ("resources/read", uri), **kw
),
uri,
)
def _resource_contents(blocks: Any, uri: str) -> dict:
"""Keyed as McpUiResourceResponse. Of several contents the one matching ``uri`` wins, else the first."""
import base64
items = list(blocks or [])
if not items:
raise ValueError("resource is empty")
chosen = next((b for b in items if str(getattr(b, "uri", "")) == uri), items[0])
text, blob = getattr(chosen, "text", None), None
if text is None:
if getattr(chosen, "blob", None) is None:
raise ValueError("resource carries neither text nor blob content")
blob = str(chosen.blob)
try:
raw = base64.b64decode(blob, validate = True)
except Exception as exc: # noqa: BLE001
raise ValueError(f"resource blob is not base64: {exc}") from exc
try:
# Decoded for the host to render a template; the widget still gets the server's blob.
text = raw.decode("utf-8")
except UnicodeDecodeError:
text = ""
text = str(text)
# Every block for a widget's own multi-block read; a single block is the fields above.
contents = []
for item in items if len(items) > 1 else ():
entry = {"uri": str(getattr(item, "uri", "") or uri)}
if _resource_mime(item):
entry["mimeType"] = str(_resource_mime(item))
if getattr(item, "text", None) is not None:
entry["text"] = str(item.text)
elif getattr(item, "blob", None) is not None:
entry["blob"] = str(item.blob)
else:
continue
contents.append(entry)
size = (
len(text)
+ len(blob or "")
+ sum(len(c.get("text") or c.get("blob") or "") for c in contents)
)
if size > MAX_UI_RESOURCE_CHARS:
raise ValueError(f"resource is {size} chars, over the {MAX_UI_RESOURCE_CHARS} limit")
# _meta.ui on the contents, not the tool: the template's CSP declaration.
metas = (getattr(chosen, "meta", None), getattr(chosen, "_meta", None))
ui = next((m["ui"] for m in metas if isinstance(m, dict) and isinstance(m.get("ui"), dict)), {})
mime = str(_resource_mime(chosen) or "")
return {
"uri": uri,
"mime_type": mime,
"text": text,
"blob": blob,
"ui": ui,
"contents": contents,
}
class _MCPCancelled(Exception):
"""Internal sentinel raised when cancel_event fires before the tool returns."""