mcpsnare 0.3.0__py3-none-any.whl

mcpsnare/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

mcpsnare/__main__.py

@@ -0,0 +1,4 @@
+from mcpsnare.cli import main
+
+if __name__ == "__main__":
+    main()

mcpsnare/checks/__init__.py

@@ -0,0 +1,2 @@
+from mcpsnare.checks import (path_traversal, info_leak, cmd_injection, ssrf, auth_bypass,  # noqa: F401
+                            sql_injection)  # noqa: F401

mcpsnare/checks/auth_bypass.py

@@ -0,0 +1,48 @@
+import re
+from mcpsnare.models import Probe, Finding, Severity, Confidence
+from mcpsnare.checks.base import register
+
+# Volatile substrings stripped before the tolerant compare, so a bypass is detected
+# even when the two bodies differ only by a timestamp / request-id / nonce. NOTE: a
+# bare record "id" is intentionally NOT stripped - a different record id is a real data
+# difference, not a volatile field, and stripping it would risk a false bypass.
+_VOLATILE = re.compile(
+    r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?"          # ISO timestamps
+    r"|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"  # UUIDs
+    r"|\"(?:ts|timestamp|nonce|request[_-]?id|trace[_-]?id)\"\s*:\s*\"?[^\",}]*\"?",
+    re.IGNORECASE,
+)
+
+
+def _normalize(s: str) -> str:
+    return _VOLATILE.sub("", s or "").strip()
+
+
+@register
+class AuthBypass:
+    id = "auth_bypass"
+    def generate(self, point, ctx):
+        if ctx.transport != "http" or ctx.call_tool_unauth is None:
+            return []
+        return [Probe(check=self.id, point=point, payload="<no auth header>",
+                      args=dict(point.base_args), meta={"needs_unauth": True})]
+    def evaluate(self, probe, response, ctx):
+        unauth = probe.meta.get("unauth_response")
+        if not unauth:
+            return None
+        if unauth == response:
+            # Raw byte-identical: a clear, directly-observed bypass.
+            return self._finding(probe, Confidence.CONFIRMED,
+                                 "tool callable without auth header (identical response)")
+        nu, nr = _normalize(unauth), _normalize(response)
+        if nu and nu == nr:
+            # Match only after stripping volatile fields: strong but inferred -> FIRM.
+            return self._finding(probe, Confidence.FIRM,
+                                 "tool callable without auth header (responses match modulo volatile fields)")
+        return None
+    def _finding(self, probe, conf, evidence):
+        return Finding(check=self.id, tool=probe.point.tool, param="-",
+                       severity=Severity.HIGH, confidence=conf, cwe="CWE-306",
+                       title=f"Missing authentication on {probe.point.tool}",
+                       payload=probe.payload, evidence=evidence,
+                       remediation="Enforce auth on the HTTP transport for all sensitive tools.")

mcpsnare/checks/base.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+from typing import Callable, Protocol
+from mcpsnare.models import InjectionPoint, Probe, Finding, ToolBaseline
+
+
+@dataclass
+class CheckContext:
+    oob: object | None
+    transport: str
+    call_tool: Callable[[str, dict], str] | None = None
+    call_tool_unauth: Callable[[str, dict], str] | None = None
+    baseline: ToolBaseline | None = None
+    aggressive: bool = False
+
+
+class Check(Protocol):
+    id: str
+    def generate(self, point: InjectionPoint, ctx: "CheckContext") -> list[Probe]: ...
+    def evaluate(self, probe: Probe, response: str, ctx: "CheckContext") -> Finding | None: ...
+
+
+REGISTRY: dict[str, "Check"] = {}
+
+
+def register(cls):
+    REGISTRY[cls.id] = cls()
+    return cls

mcpsnare/checks/cmd_injection.py

@@ -0,0 +1,73 @@
+from mcpsnare.models import Probe, Finding, Severity, Confidence
+from mcpsnare.checks.base import register
+
+_SLEEP_SECONDS = 5
+_LATENCY_MULT = 3
+
+# OOB confirmation payloads: each triggers an outbound request to {url}. Covers POSIX
+# sh, Windows cmd.exe, and PowerShell, deduped. Non-blocking (always sent).
+_OOB_TEMPLATES = (
+    "; curl {url}",          # POSIX
+    "$(curl {url})",         # POSIX command substitution
+    "& curl {url}",          # cmd.exe / POSIX background
+    "| curl {url}",          # cmd.exe / POSIX pipe
+    "; iwr {url}",           # PowerShell (Invoke-WebRequest)
+    "; curl.exe {url}",      # PowerShell (real curl, not the iwr alias)
+)
+
+# Blocking time-based payloads (~_SLEEP_SECONDS delay), sent only with --aggressive.
+_SLEEP_TEMPLATES = (
+    "; sleep {n}",                # POSIX
+    "$(sleep {n})",               # POSIX command substitution
+    "& ping -n {n1} 127.0.0.1",   # cmd.exe (no sleep builtin; ping ~1s/echo)
+    "; Start-Sleep -s {n}",       # PowerShell
+)
+
+@register
+class CmdInjection:
+    id = "cmd_injection"
+    def generate(self, point, ctx):
+        probes = []
+        if ctx.oob is not None:
+            for tpl in _OOB_TEMPLATES:
+                token, url = ctx.oob.new_token()
+                cmd = tpl.format(url=url)                  # separator+command, e.g. "; curl <url>"
+                whole_args = point.set(f"mcpsnare{cmd}")
+                embed_args = point.embed(cmd)             # valid-value prefix + cmd
+                variants = [whole_args]
+                if embed_args != whole_args:
+                    variants.append(embed_args)
+                for args in variants:
+                    from mcpsnare.inject.jsonpath import deep_get
+                    payload = deep_get(args, point.json_path)
+                    probes.append(Probe(check=self.id, point=point, payload=str(payload),
+                                        args=args, token=token))
+        if getattr(ctx, "aggressive", False):
+            for tpl in _SLEEP_TEMPLATES:
+                pl = f"mcpsnare{tpl.format(n=_SLEEP_SECONDS, n1=_SLEEP_SECONDS + 1)}"
+                probes.append(Probe(check=self.id, point=point, payload=pl, args=point.set(pl),
+                                    meta={"time_based": True, "threshold": _SLEEP_SECONDS}))
+        return probes
+    def evaluate(self, probe, response, ctx):
+        if probe.token and ctx.oob and ctx.oob.interactions(probe.token):
+            return self._finding(probe, Confidence.CONFIRMED,
+                                 f"OOB callback received for payload {probe.payload!r}")
+        if probe.meta.get("time_based"):
+            elapsed = probe.meta.get("elapsed", 0)
+            sleep_s = probe.meta["threshold"]
+            baseline = getattr(ctx, "baseline", None)
+            if baseline is not None:
+                margin = max(baseline.latency + sleep_s * 0.8, baseline.latency * _LATENCY_MULT)
+                evidence = f"response delayed {elapsed:.1f}s vs baseline {baseline.latency:.1f}s"
+            else:
+                margin = sleep_s  # no calibration: fall back to the fixed threshold
+                evidence = f"response delayed {elapsed:.1f}s"
+            if elapsed >= margin:
+                return self._finding(probe, Confidence.FIRM, evidence)
+        return None
+    def _finding(self, probe, conf, evidence):
+        return Finding(check=self.id, tool=probe.point.tool, param=probe.point.param_name,
+                       severity=Severity.CRITICAL, confidence=conf, cwe="CWE-78",
+                       title=f"Command injection in {probe.point.tool}.{probe.point.param_name}",
+                       payload=probe.payload, evidence=evidence,
+                       remediation="Never pass tool input to a shell; use exec with arg arrays / allowlists.")

mcpsnare/checks/info_leak.py

@@ -0,0 +1,43 @@
+import re
+from mcpsnare.models import Probe, Finding, Severity, Confidence
+from mcpsnare.checks.base import register
+
+_MARKERS = [re.compile(p) for p in [
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----", r"AKIA[0-9A-Z]{16}",
+    r"(?i)api[_-]?key\s*[=:]\s*\S+", r"(?i)secret\s*[=:]\s*\S+",
+    r"xox[baprs]-[0-9A-Za-z-]+", r"eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\."]]
+
+
+@register
+class InfoLeak:
+    id = "info_leak"
+    def generate(self, point, ctx):
+        return [Probe(check=self.id, point=point, payload="mcpsnare-probe",
+                      args=point.set("mcpsnare-probe"))]
+    def evaluate(self, probe, response, ctx):
+        hits = [m.pattern for m in _MARKERS if m.search(response or "")]
+        if not hits:
+            return None
+        baseline = getattr(ctx, "baseline", None)
+        if baseline is not None:
+            # Diff by which PATTERN matched, not the matched substring: this favors FP
+            # elimination (a docs tool with a fixed example key is suppressed). Known
+            # trade-off (disclosed in docs/claims-matrix.md): a baseline placeholder and
+            # a real leak of the SAME shape both match one pattern, so such a leak is missed.
+            base_hits = {m.pattern for m in _MARKERS if m.search(baseline.response or "")}
+            triggered = [h for h in hits if h not in base_hits]
+            if not triggered:
+                return None  # secrets also present in benign baseline = normal output, not a leak
+            return self._finding(probe, Confidence.FIRM,
+                                 f"secret-shaped match triggered by input (absent in baseline): {triggered}")
+        if len(hits) >= 2:
+            return self._finding(probe, Confidence.TENTATIVE,
+                                 f"secret-shaped pattern match (no baseline to diff): {hits}")
+        return None
+
+    def _finding(self, probe, conf, evidence):
+        return Finding(check=self.id, tool=probe.point.tool, param=probe.point.param_name,
+                       severity=Severity.HIGH, confidence=conf, cwe="CWE-200",
+                       title=f"Secret/info leak via {probe.point.tool}",
+                       payload=probe.payload, evidence=evidence,
+                       remediation="Never return secrets/credentials in tool output or errors.")

mcpsnare/checks/path_traversal.py

@@ -0,0 +1,25 @@
+import re
+from mcpsnare.models import Probe, Finding, Severity, Confidence
+from mcpsnare.checks.base import register
+
+_PAYLOADS = ["../../../../../../etc/passwd",
+             "..\\..\\..\\..\\..\\..\\windows\\win.ini"]
+_CANARY = re.compile(r"root:x:0:0:|\[fonts\]", re.IGNORECASE)
+
+
+@register
+class PathTraversal:
+    id = "path_traversal"
+    def generate(self, point, ctx):
+        out = []
+        for pl in _PAYLOADS:
+            out.append(Probe(check=self.id, point=point, payload=pl, args=point.set(pl)))
+        return out
+    def evaluate(self, probe, response, ctx):
+        if _CANARY.search(response or ""):
+            return Finding(check=self.id, tool=probe.point.tool, param=probe.point.param_name,
+                           severity=Severity.HIGH, confidence=Confidence.CONFIRMED, cwe="CWE-22",
+                           title=f"Path traversal in {probe.point.tool}.{probe.point.param_name}",
+                           payload=probe.payload, evidence=(response or "")[:200],
+                           remediation="Resolve and contain paths within an allowed base dir.")
+        return None

mcpsnare/checks/sql_injection.py

@@ -0,0 +1,76 @@
+import re
+from mcpsnare.models import Probe, Finding, Severity, Confidence
+from mcpsnare.checks.base import register
+
+_SLEEP_SECONDS = 5
+_LATENCY_MULT = 3
+
+# Distinctive SQL error signatures across common engines.
+_ERROR_SIGNS = re.compile(
+    r"SQL syntax|SQLSTATE|ORA-\d{5}|mysql_fetch|mysql_num_rows|"
+    r"unclosed quotation mark|quoted string not properly terminated|"
+    r"you have an error in your SQL|near \"[^\"]*\": syntax error|"
+    r"PG::\w+Error|pg_query|psql:.*(?:ERROR|FATAL)|SQLite3?::|Microsoft OLE DB|"
+    r"ODBC SQL Server|Npgsql\.|System\.Data\.SqlClient",
+    re.IGNORECASE,
+)
+
+# Non-blocking error-based payloads (always sent).
+_ERROR_PAYLOADS = ("'", '"', "')", "' OR '1'='1")
+
+# Blocking time-based payloads (~_SLEEP_SECONDS), aggressive-only. MySQL, MSSQL, PostgreSQL.
+_TIME_TEMPLATES = (
+    "' OR SLEEP({n})-- ",
+    "'; WAITFOR DELAY '0:0:{n}'-- ",
+    "' OR pg_sleep({n})-- ",
+)
+
+
+@register
+class SqlInjection:
+    id = "sql_injection"
+
+    def generate(self, point, ctx):
+        probes = []
+        for pl in _ERROR_PAYLOADS:
+            probes.append(Probe(check=self.id, point=point, payload=pl,
+                                args=point.set(pl), meta={"error_based": True}))
+        if getattr(ctx, "aggressive", False):
+            for tpl in _TIME_TEMPLATES:
+                pl = tpl.format(n=_SLEEP_SECONDS)
+                probes.append(Probe(check=self.id, point=point, payload=pl,
+                                    args=point.set(pl),
+                                    meta={"time_based": True, "threshold": _SLEEP_SECONDS}))
+        return probes
+
+    def evaluate(self, probe, response, ctx):
+        if probe.meta.get("time_based"):
+            elapsed = probe.meta.get("elapsed", 0)
+            sleep_s = probe.meta["threshold"]
+            baseline = getattr(ctx, "baseline", None)
+            if baseline is not None:
+                margin = max(baseline.latency + sleep_s * 0.8, baseline.latency * _LATENCY_MULT)
+                evidence = f"response delayed {elapsed:.1f}s vs baseline {baseline.latency:.1f}s (SQL sleep)"
+            else:
+                margin = sleep_s
+                evidence = f"response delayed {elapsed:.1f}s (SQL sleep)"
+            if elapsed >= margin:
+                return self._finding(probe, Confidence.FIRM, evidence)
+            return None
+        if not _ERROR_SIGNS.search(response or ""):
+            return None
+        baseline = getattr(ctx, "baseline", None)
+        if baseline is not None:
+            if _ERROR_SIGNS.search(baseline.response or ""):
+                return None  # error already in benign baseline = not triggered
+            return self._finding(probe, Confidence.FIRM,
+                                 "SQL error signature triggered by quote payload (absent in baseline)")
+        return self._finding(probe, Confidence.TENTATIVE,
+                             "SQL error signature matched (no baseline to corroborate)")
+
+    def _finding(self, probe, conf, evidence):
+        return Finding(check=self.id, tool=probe.point.tool, param=probe.point.param_name,
+                       severity=Severity.HIGH, confidence=conf, cwe="CWE-89",
+                       title=f"SQL injection in {probe.point.tool}.{probe.point.param_name}",
+                       payload=probe.payload, evidence=evidence,
+                       remediation="Use parameterised queries / prepared statements; never concatenate input into SQL.")

mcpsnare/checks/ssrf.py

@@ -0,0 +1,19 @@
+from mcpsnare.models import Probe, Finding, Severity, Confidence
+from mcpsnare.checks.base import register
+
+@register
+class SSRF:
+    id = "ssrf"
+    def generate(self, point, ctx):
+        if ctx.oob is None:
+            return []
+        token, url = ctx.oob.new_token()
+        return [Probe(check=self.id, point=point, payload=url, args=point.set(url), token=token)]
+    def evaluate(self, probe, response, ctx):
+        if probe.token and ctx.oob and ctx.oob.interactions(probe.token):
+            return Finding(check=self.id, tool=probe.point.tool, param=probe.point.param_name,
+                           severity=Severity.HIGH, confidence=Confidence.CONFIRMED, cwe="CWE-918",
+                           title=f"SSRF in {probe.point.tool}.{probe.point.param_name}",
+                           payload=probe.payload, evidence="OOB callback received",
+                           remediation="Validate/allowlist outbound URLs; block internal ranges & metadata IPs.")
+        return None

mcpsnare/cli.py

@@ -0,0 +1,118 @@
+import argparse
+import asyncio
+import os
+import shlex
+import sys
+
+from mcpsnare.report.render import to_json, to_sarif, to_markdown
+
+
+def _positive_float(s):
+    v = float(s)
+    if v <= 0:
+        raise argparse.ArgumentTypeError("must be > 0")
+    return v
+
+
+def aggressive_note(aggressive: bool) -> str | None:
+    """Honest note for default (non-aggressive) scans: blocking time-based probes
+    were skipped, so an empty report must not be read as 'secure'. None when
+    aggressive (nothing was skipped)."""
+    if aggressive:
+        return None
+    return ("[i] Default mode: blocking time-based probes were skipped. "
+            "Re-run with --aggressive to add time-based command-injection and SQL-injection detection.")
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="mcpsnare")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("scan", help="scan an MCP server")
+    g = s.add_mutually_exclusive_group(required=True)
+    g.add_argument("--stdio", help='command to launch the server, e.g. "python server.py"')
+    g.add_argument("--http", help="streamable HTTP MCP endpoint URL")
+    s.add_argument("--header", action="append", default=[], help="HTTP header k:v (repeatable)")
+    s.add_argument("--oob", choices=["local", "interactsh", "none"], default="local")
+    s.add_argument("--interactsh-server", default="oast.fun",
+                   help="interactsh/OAST server domain for --oob interactsh (default oast.fun)")
+    s.add_argument("--aggressive", action="store_true",
+                   help="also send blocking time-based (sleep) probes; default sends only non-blocking OOB/canary/pattern probes")
+    s.add_argument("--concurrency", type=int, default=4,
+                   help="max concurrent probe requests (default 4)")
+    s.add_argument("--rate", type=_positive_float, default=None,
+                   help="max requests/second (default unlimited)")
+    s.add_argument("--oob-timeout", type=float, default=20.0,
+                   help="seconds to poll for OOB callbacks (default 20)")
+    s.add_argument("--oob-poll-interval", type=float, default=2.5,
+                   help="OOB poll interval seconds (default 2.5)")
+    s.add_argument("--output", choices=["console", "json", "sarif", "md"], default="console")
+    return p
+
+
+async def _run(args):
+    from mcpsnare.connect.session import stdio_session, http_session
+    from mcpsnare.connect.resources import ResourceToolView
+    from mcpsnare.engine import scan_session
+    import mcpsnare.checks  # register
+    from mcpsnare.oob.local import LocalOOB
+
+    print("[!] mcpsnare - authorized testing only.")
+    oob_cm = None
+    oob = None
+    if args.oob == "local":
+        oob_cm = LocalOOB()
+        oob = oob_cm.__enter__()
+    elif args.oob == "interactsh":
+        from mcpsnare.oob.interactsh import InteractshOOB
+        from mcpsnare.oob.interactsh_client import InteractshClient
+        oob = InteractshOOB(InteractshClient(server=args.interactsh_server))
+    try:
+        if args.stdio:
+            argv = shlex.split(args.stdio, posix=(os.name != "nt"))
+            async with stdio_session(argv) as sess:
+                findings = await scan_session(sess, oob=oob, transport="stdio", aggressive=args.aggressive,
+                                              concurrency=args.concurrency, rate=args.rate,
+                                              oob_timeout=args.oob_timeout,
+                                              oob_poll_interval=args.oob_poll_interval)
+                findings += await scan_session(ResourceToolView(sess), oob=oob, transport="stdio",
+                                               aggressive=args.aggressive, concurrency=args.concurrency,
+                                               rate=args.rate, check_ids=["path_traversal", "info_leak"])
+        else:
+            headers = dict(h.split(":", 1) for h in args.header)
+            async with http_session(args.http, headers=headers) as sess:
+                if headers:
+                    async with http_session(args.http, headers={}) as sess_unauth:
+                        findings = await scan_session(sess, oob=oob, transport="http",
+                                                      call_tool_unauth=sess_unauth.call_tool, aggressive=args.aggressive,
+                                                      concurrency=args.concurrency, rate=args.rate,
+                                                      oob_timeout=args.oob_timeout,
+                                                      oob_poll_interval=args.oob_poll_interval)
+                        findings += await scan_session(ResourceToolView(sess), oob=oob, transport="http",
+                                                       aggressive=args.aggressive, concurrency=args.concurrency,
+                                                       rate=args.rate, check_ids=["path_traversal", "info_leak"])
+                else:
+                    findings = await scan_session(sess, oob=oob, transport="http", aggressive=args.aggressive,
+                                                  concurrency=args.concurrency, rate=args.rate,
+                                                  oob_timeout=args.oob_timeout,
+                                                  oob_poll_interval=args.oob_poll_interval)
+                    findings += await scan_session(ResourceToolView(sess), oob=oob, transport="http",
+                                                   aggressive=args.aggressive, concurrency=args.concurrency,
+                                                   rate=args.rate, check_ids=["path_traversal", "info_leak"])
+    finally:
+        if oob_cm:
+            oob_cm.__exit__(None, None, None)
+    renderers = {"json": to_json, "sarif": to_sarif, "md": to_markdown}
+    if args.output in renderers:
+        print(renderers[args.output](findings))
+    else:
+        print(f"\n{len(findings)} finding(s):")
+        for f in findings:
+            print(f"  [{f.severity.value.upper()}] {f.title}  ({f.confidence.value})")
+    note = aggressive_note(args.aggressive)
+    if note:
+        print(note, file=sys.stderr)
+
+
+def main():
+    args = build_parser().parse_args()
+    asyncio.run(_run(args))

mcpsnare/connect/resources.py

@@ -0,0 +1,42 @@
+import re
+
+from mcpsnare.models import ToolInfo
+
+_TMPL_PARAM = re.compile(r"\{([^}/]+)\}")
+
+
+class ResourceToolView:
+    """Presents an object's resource templates as tool-like objects so the existing
+    engine (injection_points + checks + oracles) can scan resources. A templated
+    ``{param}`` in a URI template becomes a string injection point; ``call_tool`` fills
+    the template and ``read_resource``s it.
+
+    The wrapped object must expose ``list_resource_templates() -> list[(name, uriTemplate)]``
+    and ``read_resource(uri) -> str`` (mcpsnare's Session does).
+    """
+
+    def __init__(self, session):
+        self._session = session
+        self._templates = {}  # tool_name -> uriTemplate
+
+    async def list_tools(self):
+        tools = []
+        for name, tmpl in await self._session.list_resource_templates():
+            params = _TMPL_PARAM.findall(tmpl)
+            if not params:
+                continue
+            props = {p: {"type": "string"} for p in params}
+            schema = {"type": "object", "properties": props, "required": params}
+            tool_name = f"resource:{tmpl}"
+            self._templates[tool_name] = tmpl
+            tools.append(ToolInfo(name=tool_name, description=name, input_schema=schema))
+        return tools
+
+    async def call_tool(self, name, args):
+        # Precondition: list_tools() must run first to populate self._templates.
+        # scan_session always calls list_tools() before any call_tool(), so this holds.
+        tmpl = self._templates[name]
+        uri = tmpl
+        for key, value in args.items():
+            uri = uri.replace("{" + key + "}", str(value))
+        return await self._session.read_resource(uri)

mcpsnare/connect/session.py

@@ -0,0 +1,68 @@
+from contextlib import asynccontextmanager
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
+
+from mcpsnare.models import ToolInfo
+
+
+class Session:
+    def __init__(self, cs):
+        self._cs = cs
+
+    async def list_tools(self):
+        resp = await self._cs.list_tools()
+        return [
+            ToolInfo(
+                name=t.name,
+                description=t.description or "",
+                input_schema=t.inputSchema or {},
+            )
+            for t in resp.tools
+        ]
+
+    async def call_tool(self, name, args):
+        resp = await self._cs.call_tool(name, args)
+        parts = []
+        for c in resp.content:
+            parts.append(getattr(c, "text", "") or "")
+        structured = getattr(resp, "structuredContent", None)
+        if structured:
+            import json
+            parts.append(json.dumps(structured, default=str))
+        return "\n".join(p for p in parts if p)
+
+    async def list_resource_templates(self):
+        resp = await self._cs.list_resource_templates()
+        return [(t.name, t.uriTemplate) for t in resp.resourceTemplates]
+
+    async def read_resource(self, uri):
+        resp = await self._cs.read_resource(uri)
+        parts = []
+        for c in resp.contents:
+            parts.append(getattr(c, "text", "") or "")
+        return "\n".join(p for p in parts if p)
+
+
+@asynccontextmanager
+async def stdio_session(command):
+    params = StdioServerParameters(command=command[0], args=command[1:])
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as cs:
+            await cs.initialize()
+            yield Session(cs)
+
+
+@asynccontextmanager
+async def http_session(url, headers=None):
+    # The SDK's streamable_http_client takes headers via a caller-owned httpx client
+    # (the old headers= kwarg is gone). create_mcp_http_client applies the same MCP
+    # defaults the old path used (30s timeout, 300s SSE read, follow_redirects), so
+    # routing headers through it is behaviour-preserving - not a bare AsyncClient,
+    # which would default to a ~5s read timeout and break long-lived streams.
+    async with create_mcp_http_client(headers=headers or {}) as http_client:
+        async with streamable_http_client(url, http_client=http_client) as (read, write, *_):
+            async with ClientSession(read, write) as cs:
+                await cs.initialize()
+                yield Session(cs)