fix(mcp): raise the FastMCP runtime ToolError instead of the legacy MCP SDK class

[phernandez]

Summary

Core raises the legacy MCP SDK ToolError from mcp.server.fastmcp.exceptions, even though the server runtime is FastMCP 3.x and hosted middleware handles fastmcp.exceptions.ToolError.

Those are different Python classes. As a result, a structured hosted API error can escape the Cloud middleware as a bare tool failure instead of being converted into the intended friendly MCP result.

Evidence

Core currently imports the legacy class in the shared HTTP helper:

• src/basic_memory/mcp/tools/utils.py:33
• several individual tools and project-context paths use the same import

Under the currently locked dependencies:

from fastmcp.exceptions import ToolError as FastMCPToolError
from mcp.server.fastmcp.exceptions import ToolError as LegacyToolError

assert LegacyToolError is not FastMCPToolError
assert not issubclass(LegacyToolError, FastMCPToolError)

The concrete hosted failure is:

1. Cloud's tenant API returns a structured 403 subscription_required response with a subscribe URL.
2. Core's HTTP helper catches httpx.HTTPStatusError and wraps it in the legacy SDK ToolError.
3. Cloud middleware catches the FastMCP runtime ToolError.
4. The class mismatch bypasses conversion, so tools such as recent_activity surface only Active subscription required instead of the actionable subscription result.

Cloud can temporarily recognize both classes, but Core should emit the exception type owned by its active FastMCP runtime.

Proposed fix

• While Core remains on FastMCP 3.x, replace legacy mcp.server.fastmcp.exceptions.ToolError imports with fastmcp.exceptions.ToolError across the MCP tool/runtime surface.
• Keep the original httpx.HTTPStatusError as the explicit cause so hosted middleware can inspect structured response details.
• Add a focused regression test proving the shared HTTP helper raises the FastMCP runtime class and preserves the HTTP cause.
• Audit tests and deferred imports that still name the legacy SDK class.

Acceptance criteria

• Core MCP tools consistently raise the ToolError class expected by the active FastMCP runtime.
• Shared HTTP helpers preserve httpx.HTTPStatusError as __cause__.
• Hosted middleware can catch a Core tool error without a compatibility import for the legacy MCP SDK class.
• Unrelated tool errors continue to fail loudly.
• Focused MCP tests and repository checks pass.

Related

• feat(mcp): adopt FastMCP 4 beta and validate hosted MCP Apps #1181 tracks the FastMCP 4 beta port. That port may use a different supported exception path; this issue is the narrower current-runtime bug and should not wait on the full upgrade.
• basicmachines-co/basic-memory-cloud#1666 exposed the inconsistent agent-facing subscription error while testing hosted MCP tools.

[claude]

Claude finished @phernandez's task in 1m 55s —— View job

---

Triage complete

• Read issue and gather context
• Classify type/priority/component/complexity
• Check for duplicate issues
• Apply labels
• Post triage summary comment

Classification

• Type: Bug report (already labeled bug)
• Component: MCP tools (specifically the shared HTTP error-handling path used by MCP tools, shared with Cloud's hosted middleware)
• Priority: High — this isn't cosmetic; a real hosted failure (recent_activity subscription check) is currently surfacing as a bare tool error instead of the intended actionable/friendly result, because Core raises mcp.server.fastmcp.exceptions.ToolError while Cloud's middleware catches fastmcp.exceptions.ToolError. No repo priority:* labels exist to apply, so this is reflected here in the comment.
• Complexity: Medium — the fix itself (swap the exception import) is mechanical, but it's spread across ~15 source files (mcp/tools/*.py, mcp/project_context.py, several cli/commands/*.py) and ~15 test files that import the legacy class, so it needs a careful audit pass rather than a single-line patch. No repo complexity:* labels exist to apply.

Verification

I confirmed the evidence in the issue against the current main branch — the legacy import from mcp.server.fastmcp.exceptions import ToolError is indeed still present at src/basic_memory/mcp/tools/utils.py:33, plus in edit_note.py, move_note.py, build_context.py, read_content.py, delete_note.py, project_context.py (x2), and several cli/commands/*.py files, along with ~15 test files. The issue's root-cause analysis is accurate and reproducible from the code as described.

Duplicate check

No existing open/closed issue duplicates this. #1181 (FastMCP 4 beta port) is related but distinct in scope, as the issue itself already notes — this bug is about the current FastMCP 3.x runtime and shouldn't wait on that upgrade.

Labels applied

• production — this is an observed production bug (hosted recent_activity subscription error surfacing incorrectly), not just a theoretical mismatch
• cloud — the failure mode only manifests at the Core/Cloud middleware boundary

Note: the repo's actual label set doesn't include mcp, mcp-tool, priority tiers (high/medium/low), or complexity tiers (simple/medium/complex) mentioned in the triage instructions — I verified the real taxonomy via gh search issues (labels in use: bug, production, enhancement, cloud, documentation, duplicate, arch-review, needs investigation, v1.0, On Hold) and only applied labels that exist.

Per triage scope, no code changes, branches, or commits were made — this is a well-specified bug with clear reproduction/evidence and a proposed fix already in the issue body, ready for implementation in a follow-up.

[phernandez]

@claude make a pr

[claude]

Claude finished @phernandez's task in 10m 4s —— View job • claude/issue-1197-20260805-2002 • Create PR ➔

---

Tasks

• Read issue and gather context
• Find all legacy mcp.server.fastmcp.exceptions.ToolError usages (source + tests)
• Replace with fastmcp.exceptions.ToolError across MCP tool/runtime surface
• Preserve httpx.HTTPStatusError as __cause__
• Update tests referencing the legacy class
• Add regression test for the shared HTTP helper
• Run lint/typecheck/tests
• Commit, push, open PR

Summary

Swapped every legacy mcp.server.fastmcp.exceptions.ToolError import for fastmcp.exceptions.ToolError across the MCP tool/runtime surface:

• mcp/tools/utils.py, edit_note.py, move_note.py, delete_note.py, read_content.py, build_context.py, mcp/project_context.py
• CLI commands that defer the import to avoid loading the MCP SDK at CLI startup (CLI eagerly imports embedding stack (onnxruntime/fastembed) for filter-only search-notes → slow SessionStart brief #886): cli/commands/command_utils.py, doctor.py, orphans.py, status.py — kept these deferred, just repointed the module path and updated the comment
• ~15 test files that imported the legacy class

The existing raise ToolError(...) from e pattern in mcp/tools/utils.py already preserved the httpx.HTTPStatusError cause, so no behavior change was needed there — only the exception class. Added a regression test in tests/mcp/test_tool_utils.py (test_call_get_error_raises_fastmcp_runtime_tool_error) asserting call_get raises the FastMCP runtime ToolError (not the legacy SDK class) with the cause preserved.

Verification

• just fast-check (lint + format): passes. typecheck reports 4 pre-existing pymilvus unresolved-import errors — unrelated to this change (optional dependency not installed in this sandbox).
• Targeted pytest across all touched MCP/CLI test files: 257 passed.
• just doctor (end-to-end file↔DB loop): passes, exercising the ToolError-catching path in cli/commands/doctor.py.
• Confirmed in a REPL that basic_memory.mcp.tools.utils.ToolError is now fastmcp.exceptions.ToolError, distinct from the legacy mcp.server.fastmcp.exceptions.ToolError named in the issue.