No such tool available · Failed to connect · notifications/tools/list_changed

Fix

1) Write down, per server, the tools a task needs, while everything works. 2) At the start of every run, list the tools the session really has (the client's list command, the SDK's server status or the model's own tool list) and compare them with that inventory (snippet); on a MISSING-SERVER or MISSING line, stop or report instead of letting the agent fall back. 3) Where the client offers it, make the startup failure of a needed server fatal, or check server status in SDK code and reconnect; in a headless run, read the warnings, not only the exit code. 4) Give every server a name that is unique across all layers, and check the list command for a displacement warning. 5) After a server adds, removes or renames tools, reconnect it or start a new session; do not count on list_changed, and refresh a discovery cache. 6) If the server's tool count and the client's differ, simplify the missing tools' inputSchema (top-level type object). 7) In a client you write, page tools/list to the end (PC-074), refetch on list_changed and log every dropped tool by name. 8) When you run a server, keep tool names stable and keep an old name as an alias for a while.

Command

#!/usr/bin/env python3
"""mcp_tool_inventory.py 1.0 - does this session really have the MCP tools you expect?
usage: python3 mcp_tool_inventory.py --selftest            (local servers on 127.0.0.1, no network)
       python3 mcp_tool_inventory.py EXPECTED.json ACTUAL.json
EXPECTED.json: {"server": ["tool", ...], ...}, written down once when everything worked.
ACTUAL.json: what the session has now, as a list of names ("mcp__server__tool"), as
{"server": ["tool", ...]}, or as {"server": {"tools": [{"name": ...}, ...]}} (saved tools/list results).
Prints MISSING-SERVER, MISSING and EXTRA lines. Exit 0: every expected tool is there.
Exit 1: something is missing. Exit 2: usage or bad input.
The compare mode reads files only; it never connects to a server.
"""
import json, socket, sys, threading, urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


def tool(name, schema_type="object"):
    return {"name": name, "inputSchema": {"type": schema_type, "properties": {}}}


class Server:
    """A tiny MCP-like server: JSON-RPC over HTTP POST, paged tools/list, list_changed queue."""

    def __init__(self, tools, page=None):
        self.tools, self.page, self.pending, self.lock = list(tools), page, [], threading.Lock()

    def add(self, t):
        with self.lock:
            self.tools.append(t)
            self.pending.append({"jsonrpc": "2.0", "method": "notifications/tools/list_changed"})

    def handle(self, req):
        if req.get("method") == "notifications/poll":  # stands in for the listen stream
            with self.lock:
                out, self.pending = self.pending, []
            return out
        if req.get("method") != "tools/list":
            return {"error": {"code": -32601, "message": "method not found"}}
        with self.lock:
            tools = list(self.tools)
        if not self.page:
            return {"tools": tools}
        start = int((req.get("params") or {}).get("cursor") or 0)
        res = {"tools": tools[start:start + self.page]}
        if start + self.page < len(tools):
            res["nextCursor"] = str(start + self.page)
        return res


def serve(server):
    class H(BaseHTTPRequestHandler):
        def log_message(self, *a):
            pass

        def do_POST(self):
            req = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
            data = json.dumps({"jsonrpc": "2.0", "id": req.get("id"), "result": server.handle(req)}).encode()
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(data)))
            self.end_headers()
            self.wfile.write(data)

    httpd = ThreadingHTTPServer(("127.0.0.1", 0), H)
    threading.Thread(target=httpd.serve_forever, daemon=True).start()
    return httpd, "http://127.0.0.1:%d/mcp" % httpd.server_port


def rpc(url, method, params=None):
    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}).encode()
    req = urllib.request.Request(url, body, {"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=5) as r:
        return json.loads(r.read())["result"]


def list_tools(url, all_pages):
    tools, cursor = [], None
    for _ in range(100):
        res = rpc(url, "tools/list", {} if cursor is None else {"cursor": cursor})
        tools += res["tools"]
        cursor = res.get("nextCursor")
        if cursor is None or not all_pages:
            break
    return tools


def connect(config, careful):
    """Return ({server: [tool names]}, warnings), the way a client builds its tool table."""
    merged, warnings, seen = {}, [], {}
    for layer, servers in config:                      # later layers win, like many clients
        for name, url in servers.items():
            if name in seen and seen[name][1] != url:
                warnings.append("server name %s: the %s entry displaces the %s entry" % (name, layer, seen[name][0]))
            seen[name] = (layer, url)
            merged[name] = url
    table = {}
    for name, url in merged.items():
        try:
            tools = list_tools(url, all_pages=careful)
        except OSError as e:
            warnings.append("server %s failed to connect: %s" % (name, type(e).__name__))
            continue                                   # the session goes on without its tools
        kept = [t["name"] for t in tools if t.get("inputSchema", {}).get("type") == "object"]
        if len(kept) != len(tools):
            warnings.append("server %s reports %d tools, %d usable" % (name, len(tools), len(kept)))
        table[name] = kept
    return table, warnings


def refresh(table, urls, careful):
    for name, url in urls.items():
        if rpc(url, "notifications/poll") and careful:
            table[name] = [t["name"] for t in list_tools(url, True) if t["inputSchema"]["type"] == "object"]


def normalize(actual):
    out = {}
    if isinstance(actual, list):
        for n in actual:
            if not isinstance(n, str) or not n.startswith("mcp__") or n.count("__") < 2:
                raise ValueError("not an mcp__server__tool name: %r" % (n,))
            _, server, name = n.split("__", 2)
            out.setdefault(server, set()).add(name)
        return out
    if not isinstance(actual, dict):
        raise ValueError("ACTUAL must be a list or an object")
    for server, v in actual.items():
        if isinstance(v, dict):
            v = [t["name"] for t in v.get("tools", [])]
        out[server] = set(v)
    return out


def compare(expected, actual):
    lines = []
    for server, names in sorted(expected.items()):
        if server not in actual:
            lines.append("MISSING-SERVER %s (%d expected tools)" % (server, len(names)))
            continue
        for n in sorted(set(names) - actual[server]):
            lines.append("MISSING %s %s" % (server, n))
        for n in sorted(actual[server] - set(names)):
            lines.append("EXTRA %s %s" % (server, n))
    return lines


def selftest():
    ok = True

    def check(label, cond, detail):
        nonlocal ok
        ok = ok and cond
        print("%-58s %s" % (label, detail))

    docs = Server([tool("search"), tool("read")])
    notes_user = Server([tool("note_get"), tool("note_put")])
    notes_proj = Server([tool("todo_list")])
    big = Server([tool("t%d" % i) for i in range(1, 6)], page=2)
    odd = Server([tool("plot"), tool("render"), tool("batch", schema_type="array")])
    servers = [serve(s) for s in (docs, notes_user, notes_proj, big, odd)]
    (_, u_docs), (_, u_nu), (_, u_np), (_, u_big), (_, u_odd) = servers
    s = socket.socket()
    s.bind(("127.0.0.1", 0))
    dead = "http://127.0.0.1:%d/mcp" % s.getsockname()[1]
    s.close()                                          # nothing listens there: a server that does not start
    config = [("user", {"docs": u_docs, "notes": u_nu, "big": u_big, "odd": u_odd, "search2": dead}),
              ("project", {"notes": u_np})]
    expected = {"docs": ["read", "search"], "notes": ["note_get", "note_put"],
                "big": ["t1", "t2", "t3", "t4", "t5"], "odd": ["batch", "plot", "render"],
                "search2": ["web_search"]}
    try:
        for careful in (False, True):
            table, warnings = connect(config, careful)
            docs.add(tool("summarize"))                # added while connected, list_changed sent
            urls = {"docs": u_docs}
            refresh(table, urls, careful)
            expected_now = dict(expected, docs=["read", "search", "summarize"])
            found = compare(expected_now, {k: set(v) for k, v in table.items()})
            label = "paging, refetching client" if careful else "naive client"
            total = sum(len(v) for v in table.values())
            check("%s: tools in the session" % label, total == (11 if careful else 7),
                  "%d of 14 expected" % total)
            check("%s: warnings only, no error raised" % label, len(warnings) == 3, "%d warnings" % len(warnings))
            for w in warnings:
                print("    warning: " + w)
            want = 5 if careful else 9
            check("%s: inventory compare finds the gaps" % label, len(found) == want, "%d lines" % len(found))
            for line in found:
                print("    " + line)
            docs.tools = [t for t in docs.tools if t["name"] != "summarize"]
        reported = len(odd.tools)
        _, w = connect([("user", {"odd": u_odd})], True)
        check("unsupported schema: only the two counts differ", any("3 tools, 2 usable" in x for x in w),
              "server reports %d, client keeps 2" % reported)
        check("compare mode: a clean session exits 0",
              compare({"a": ["x"]}, normalize(["mcp__a__x", "mcp__b__y"])) == [], "no lines")
    finally:
        for httpd, _ in servers:
            httpd.shutdown()
    print("pass" if ok else "unexpected result")
    return 0 if ok else 1


def main(argv):
    if argv == ["--selftest"]:
        return selftest()
    if len(argv) != 2:
        print(__doc__.strip())
        return 2
    try:
        expected = json.load(open(argv[0], encoding="utf-8"))
        actual = normalize(json.load(open(argv[1], encoding="utf-8")))
        if not isinstance(expected, dict) or not expected:
            raise ValueError("EXPECTED must be a non-empty object")
    except (OSError, ValueError, KeyError, TypeError, AttributeError) as e:
        print("input: %s" % e)
        return 2
    lines = compare(expected, actual)
    for line in lines:
        print(line)
    missing = [x for x in lines if not x.startswith("EXTRA")]
    print("%d expected tools missing" % sum(1 for x in missing if x.startswith("MISSING ")) +
          ", %d servers missing" % sum(1 for x in missing if x.startswith("MISSING-SERVER")))
    return 1 if missing else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

Error strings

• No such tool available
• Failed to connect
• notifications/tools/list_changed

Situation

An agent runs with several MCP servers from a client's configuration (user, project, plugin or command-line layers, or connectors in a hosted app), often unattended, and its task depends on tools from those servers.

Symptom

The agent says a tool does not exist, falls back to a worse route or reports that it cannot do the task, although the same configuration worked before. A tool the server added today never shows up, or the client counts fewer tools than the server reports. A call from a resumed session fails with No such tool available. At most a warning appeared in a status view nobody reads in a headless run.

Cause

Clients treat each MCP server as optional and build the tool table from whatever answered; the model cannot miss a tool it was never shown. 1) A server that fails to connect at startup is a warning: one agent CLI continues with the other servers unless a per-server option makes the failure fatal, and Claude Code continues a claude -p run or SDK session without the tools of a stdio server whose first connection fails; without tool search it does not tell the model. A slow start ends the same way (PC-041). 2) The same server name in two configuration layers: one definition wins whole and the other is displaced with only a warning. 3) A tool list that changes while connected: the MCP specification has the server send notifications/tools/list_changed only to a client that holds the notification stream open; a client without the stream, whose stream closed or whose refresh failed keeps the old list, and one hosted connector shows new tools only after disconnect and connect. A discovery cache can also serve a list from an earlier session. 4) A tool whose inputSchema the client does not support is dropped on import; one hosted agent builder only shows two counts that differ, and zero available can also mean a wrong endpoint. 5) A loop that reads only the first page of tools/list drops the rest (PC-074), and a renamed tool is gone under its old name.

Verify

Save the snippet as mcp_tool_inventory.py and run `python3 -I mcp_tool_inventory.py --selftest` (local servers on 127.0.0.1, no network). It configures five servers in a user layer and one in a project layer: one server does not listen, the project layer reuses the name of a user server, one server pages tools/list two tools at a time, one has a tool whose inputSchema is not an object, and one adds a tool while connected and sends list_changed. Pass: (1) a naive client ends up with 7 of the 14 expected tools and only 3 warnings, and the inventory compare prints 9 lines (a missing server, the displaced tools, three tools beyond the first page, the dropped tool and the tool added later); (2) a client that pages to the end and refetches on list_changed has 11 of 14, and the compare still prints 5 lines for the failed server, the displaced name and the dropped schema; (3) for the unsupported schema only the counts differ (3 reported, 2 kept); the last line is `pass` and the exit code is 0. Negative controls: make the naive client refetch on list_changed too, keep tools of any schema, or drop the MISSING-SERVER line from the compare, and the selftest prints `unexpected result` and exits 1. Without arguments the script prints usage and exits 2. `python3 mcp_tool_inventory.py EXPECTED.json ACTUAL.json` reads files only: exit 1 with MISSING-SERVER or MISSING lines, exit 0 when every expected tool is there (EXTRA lines only), exit 2 on bad input. Checked 2026-11-11 by us with Python 3.13.5 on Linux (selftest, three negative controls, usage and three compare runs). The same day we re-read the MCP specification's tools page, Claude Code's MCP docs, one agent CLI's MCP guide and one hosted agent builder's MCP docs, which state the behaviour in the cause; one hosted connector's help page was behind a bot challenge that day, so the refetch claim rests on our reading of 2026-11-08. We did not reproduce the losses in a real client.

Source

Our own reading of vendor docs recorded in our internal signal base: one agent CLI's MCP guide (an initial connect failure is a warning and the session continues unless a per-server option makes it fatal; a colliding server name produces a warning naming the displaced source; tool-list change notifications refresh tools, but a configuration edit needs a new session), read on 2026-11-08 and 2026-11-10 and re-read on 2026-11-11; one hosted agent builder's MCP docs (tools with unsupported schemas are left out, only the two counts differ), read 2026-11-10 and re-read 2026-11-11; one hosted connector's help center (tools added later appear only after disconnect and connect), read 2026-11-08. Read on 2026-11-11: MCP specification 2026-07-28, Server Features, Tools, section List Changed Notification, at https://modelcontextprotocol.io/specification/2026-07-28/server/tools; Claude Code docs, Connect Claude Code to tools via MCP, sections Dynamic tool updates, Stdio servers that exit or fail to start, How Claude learns that a server failed, and Scope hierarchy and precedence, at https://code.claude.com/docs/en/mcp. Local runs of the snippet on 2026-11-11.

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.