feat(mcp): let a deployment declare local MCP tools (#6330)

* feat(mcp): let a deployment declare local MCP tools

Tools served by a user-configured MCP server are absent from
TOOL_CAPABILITIES, so they are unknown and fail high. For a server with
both a read and a write tool that is unusable: the read result arms the
post-external gate, because an unknown result is not SYSTEM integrity,
and the write that follows is refused until separately authorized. Every
second call needs an approval, for a server that never leaves the host.

Add ODYSSEUS_LOCAL_MCP_READ_TOOLS and ODYSSEUS_LOCAL_MCP_WRITE_TOOLS.
Declared read tools become READ_PRIVATE with SYSTEM integrity, so their
output no longer arms the gate; declared write tools become WRITE_PRIVATE
and stay inside POST_EXTERNAL_BLOCKED_EFFECTS, so a run tainted by real
external content still requires the approval. Unset variables keep the
current behaviour exactly.

Fixes #6329

* fix(mcp): secure local MCP authorization and preserve external taint gate

Keep declared local MCP read tool results untrusted with EXTERNAL_UNTRUSTED
integrity so they continue to arm the external-context gate. Introduce a
narrowly scoped continuation exception for declared local MCP writes on
the same server when no external taint or explicit error payloads enter
the run. Preserves gate protection for shell execution, network egress,
email, and cross-server actions.

Fixes #6329

* fix(mcp): resolve local continuation against stdio transport and enforce built-in classifications

Resolve declared local MCP continuation operations against connected stdio
servers and enforce established built-in tool security classifications.
Ensure remote HTTP and SSE servers, unverified transports, replaced sessions,
stale configurations, and operations with dangerous effects or missing request
grants fail closed.

* fix(mcp): require sealed authority for local continuation

* fix(mcp): seal local tool admission and synchronize GPU stacks

---------

Co-authored-by: Alexandre Teixeira <general@alexandreteixeira.dev>

src/tool_capabilities.py

@@ -334,6 +334,142 @@ _BROWSER_MCP_READ_TOOLS = frozenset(
 )
 
 
+LOCAL_MCP_READ_TOOLS_ENV = "ODYSSEUS_LOCAL_MCP_READ_TOOLS"
+LOCAL_MCP_WRITE_TOOLS_ENV = "ODYSSEUS_LOCAL_MCP_WRITE_TOOLS"
+
+_LOCAL_MCP_READ_CAPABILITIES = _capabilities(
+    ToolEffect.READ_PRIVATE,
+    result_integrity=ResultIntegrity.EXTERNAL_UNTRUSTED,
+)
+_LOCAL_MCP_WRITE_CAPABILITIES = _capabilities(
+    ToolEffect.WRITE_PRIVATE,
+    result_integrity=ResultIntegrity.EXTERNAL_UNTRUSTED,
+)
+
+
+def _local_mcp_tools(variable: str) -> frozenset[str]:
+    """Tool names a deployment declares as touching only the local store.
+
+    Tools served by a user-configured MCP server are absent from the registry
+    above, so they are classified as unknown and fail high. For a server with
+    both a read and a write tool that is unusable: the read result arms the
+    post-external gate, because an unknown result is not SYSTEM integrity, and
+    the write that follows is refused until separately authorized. Every
+    second call needs an approval, for a server that never leaves the host.
+
+    Declaring the tools resolves that without widening the gate:
+
+        ODYSSEUS_LOCAL_MCP_READ_TOOLS=mcp__<server>__search_notes,mcp__<server>__read_note
+        ODYSSEUS_LOCAL_MCP_WRITE_TOOLS=mcp__<server>__create_note
+
+    Read tools become READ_PRIVATE with EXTERNAL_UNTRUSTED integrity. Their
+    results remain untrusted and still arm the gate, preventing prompt
+    injections from reaching shell, network, or unrelated tools. However,
+    declared write tools on the exact same MCP server receive a narrowly
+    scoped continuation exception as long as no external or error taint has
+    entered the run. Once genuinely external content has entered the run,
+    approvals remain required.
+    """
+    raw = os.getenv(variable, "") or ""
+    return frozenset(name.strip() for name in raw.split(",") if name.strip())
+
+
+def _current_mcp_manager():
+    """Retrieve the current McpManager instance safely without hard circular binds."""
+    try:
+        from src import tool_execution
+        if hasattr(tool_execution, "get_mcp_manager"):
+            mgr = tool_execution.get_mcp_manager()
+            if mgr is not None:
+                return mgr
+    except Exception:
+        pass
+    try:
+        from src.tool_utils import get_mcp_manager
+        return get_mcp_manager()
+    except Exception:
+        return None
+
+
+def _is_declared_local_mcp_tool(
+    tool_name: Any, server_id: str | None = None
+) -> bool:
+    """Return whether tool_name is an exact, well-formed declared local MCP tool."""
+    if not isinstance(tool_name, str) or not tool_name:
+        return False
+    parts = tool_name.split("__", 2)
+    if not (
+        len(parts) == 3
+        and parts[0] == "mcp"
+        and bool(parts[1])
+        and bool(parts[2])
+        and not any(char.isspace() for part in parts[1:] for char in part)
+    ):
+        return False
+    sid = parts[1]
+    if server_id is not None and sid != server_id:
+        return False
+    from src.mcp_manager import McpManager
+    if McpManager.is_builtin(sid):
+        return False
+    if tool_name in TOOL_CAPABILITIES:
+        return False
+    declared_read = tool_name in _local_mcp_tools(LOCAL_MCP_READ_TOOLS_ENV)
+    declared_write = tool_name in _local_mcp_tools(LOCAL_MCP_WRITE_TOOLS_ENV)
+    return (declared_read or declared_write) and (declared_read != declared_write)
+
+
+def _is_declared_local_mcp_read_tool(
+    tool_name: Any, server_id: str | None = None
+) -> bool:
+    if not _is_declared_local_mcp_tool(tool_name, server_id):
+        return False
+    declared_read = tool_name in _local_mcp_tools(LOCAL_MCP_READ_TOOLS_ENV)
+    declared_write = tool_name in _local_mcp_tools(LOCAL_MCP_WRITE_TOOLS_ENV)
+    if not (declared_read and not declared_write):
+        return False
+    parts = tool_name.split("__", 2)
+    mgr = _current_mcp_manager()
+    if mgr is not None:
+        tools = mgr._tools.get(parts[1], [])
+        tool_row = next((r for r in tools if r.get("name") == parts[2]), None)
+        if tool_row is not None:
+            from src.mcp_manager import mcp_tool_is_readonly
+            if not mcp_tool_is_readonly(tool_row):
+                return False
+    else:
+        from src.mcp_manager import _MCP_READONLY_VERBS
+        if not parts[2].lower().startswith(_MCP_READONLY_VERBS):
+            return False
+    return True
+
+
+def _is_declared_local_mcp_write_tool(
+    tool_name: Any, server_id: str | None = None
+) -> bool:
+    if not _is_declared_local_mcp_tool(tool_name, server_id):
+        return False
+    declared_read = tool_name in _local_mcp_tools(LOCAL_MCP_READ_TOOLS_ENV)
+    declared_write = tool_name in _local_mcp_tools(LOCAL_MCP_WRITE_TOOLS_ENV)
+    if not (declared_write and not declared_read):
+        return False
+    parts = tool_name.split("__", 2)
+    mgr = _current_mcp_manager()
+    if mgr is not None:
+        tools = mgr._tools.get(parts[1], [])
+        tool_row = next((r for r in tools if r.get("name") == parts[2]), None)
+        if tool_row is not None:
+            ann = tool_row.get("annotations") or {}
+            destructive = (
+                ann.get("destructiveHint")
+                if isinstance(ann, dict)
+                else getattr(ann, "destructiveHint", None)
+            )
+            if destructive is True:
+                return False
+    return True
+
+
 def capabilities_for_tool(tool_name: Any) -> ToolCapabilities:
     """Return deterministic capabilities; malformed and unknown tools fail high."""
     if not isinstance(tool_name, str) or not tool_name:
@@ -348,6 +484,10 @@ def capabilities_for_tool(tool_name: Any) -> ToolCapabilities:
             return capabilities
     if tool_name in _BROWSER_MCP_READ_TOOLS:
         return _BROWSER_MCP_READ_CAPABILITIES
+    if _is_declared_local_mcp_read_tool(tool_name):
+        return _LOCAL_MCP_READ_CAPABILITIES
+    if _is_declared_local_mcp_write_tool(tool_name):
+        return _LOCAL_MCP_WRITE_CAPABILITIES
     return _UNKNOWN_CAPABILITIES
 
 
@@ -785,6 +925,149 @@ def delegated_tool_is_blocked(tool_name: Any, content: Any = None) -> bool:
     )
 
 
+_SERVER_OWNED_CONTROL_PLANE_SOURCES = frozenset(
+    {
+        "skills",
+        "client runtime context",
+        "backend runtime context",
+        "integrations",
+        "mcp tools",
+        "agents.md",
+    }
+)
+
+_PROHIBITED_CONTINUATION_EFFECTS = frozenset(
+    {
+        ToolEffect.NETWORK_EGRESS,
+        ToolEffect.EXTERNAL_SIDE_EFFECT,
+        ToolEffect.EXECUTE_CODE,
+        ToolEffect.ADMIN_CHANGE,
+        ToolEffect.UI_SIDE_EFFECT,
+        ToolEffect.DESTRUCTIVE,
+        ToolEffect.READ_WORKSPACE,
+        ToolEffect.WRITE_WORKSPACE,
+        ToolEffect.BROKERED_NETWORK_READ,
+        ToolEffect.READ_PUBLIC,
+    }
+)
+
+
+def _is_authorized_local_mcp_continuation(
+    tool_name: Any,
+    external_sources: Iterable[str],
+    content: Any = None,
+) -> bool:
+    """Evaluate narrowly scoped continuation for declared local MCP tools.
+
+    Allows a declared local MCP write or read tool when the tool is verified
+    against an explicitly configured and connected stdio MCP server, and the
+    only untrusted sources observed in the run are declared local MCP tools
+    belonging to the exact same MCP server (plus server-owned control plane
+    metadata).
+    """
+    if not isinstance(tool_name, str) or not tool_name:
+        return False
+    parts = tool_name.split("__", 2)
+    if len(parts) != 3 or parts[0] != "mcp" or not parts[1] or not parts[2]:
+        return False
+    server_id = parts[1]
+
+    from src.mcp_manager import McpManager
+    if McpManager.is_builtin(server_id):
+        return False
+
+    if not _is_declared_local_mcp_tool(tool_name, server_id=server_id):
+        return False
+
+    capabilities = capabilities_for_action(tool_name, content)
+    if not capabilities.known:
+        return False
+    if capabilities.effects & _PROHIBITED_CONTINUATION_EFFECTS:
+        return False
+    if capabilities.effects - {ToolEffect.WRITE_PRIVATE, ToolEffect.READ_PRIVATE}:
+        return False
+
+    manager = _current_mcp_manager()
+    if manager is None:
+        return False
+    if manager.is_builtin(server_id):
+        return False
+
+    conn = manager.get_server_status(server_id)
+    if conn.get("status") != "connected":
+        return False
+    if conn.get("transport") != "stdio":
+        return False
+
+    resource_id = manager.resource_identity(tool_name)
+    if resource_id is None or resource_id.namespace != "mcp":
+        return False
+    if resource_id.endpoint_id != f"stdio:{server_id}":
+        return False
+
+    tools_list = manager._tools.get(server_id, [])
+    tool_row = next((r for r in tools_list if r.get("name") == parts[2]), None)
+    if not tool_row:
+        return False
+    ann = tool_row.get("annotations") or {}
+    destructive = (
+        ann.get("destructiveHint")
+        if isinstance(ann, dict)
+        else getattr(ann, "destructiveHint", None)
+    )
+    if destructive is True:
+        return False
+
+    from src.agent_runtime.authority import active_request_authority, ExactOperation, RequestAuthority
+    authority = active_request_authority()
+    if not isinstance(authority, RequestAuthority):
+        return False
+    if authority is not None:
+        try:
+            operation_input = content if isinstance(content, str) else "{}"
+            operation = ExactOperation.normalize(tool_name, operation_input)
+            if not authority.permits(operation):
+                return False
+        except (ValueError, TypeError):
+            return False
+        if resource_id not in authority.backend_resources:
+            return False
+
+    sources = list(external_sources or ())
+    if not sources:
+        return False
+
+    from src.mcp_manager import mcp_tool_is_readonly
+    has_local_tool = False
+    for source in sources:
+        if source in _SERVER_OWNED_CONTROL_PLANE_SOURCES:
+            continue
+        if not _is_declared_local_mcp_tool(source, server_id=server_id):
+            return False
+        source_caps = capabilities_for_tool(source)
+        if not source_caps.known or (source_caps.effects & _PROHIBITED_CONTINUATION_EFFECTS):
+            return False
+        if source_caps.effects - {ToolEffect.READ_PRIVATE, ToolEffect.WRITE_PRIVATE}:
+            return False
+
+        source_resource = manager.resource_identity(source)
+        if source_resource is None or source_resource.endpoint_id != resource_id.endpoint_id:
+            return False
+        if not str(source_resource.endpoint_id).startswith("stdio:"):
+            return False
+
+        source_parts = source.split("__", 2)
+        source_row = next((r for r in tools_list if r.get("name") == source_parts[2]), None)
+        if not source_row:
+            return False
+        if _is_declared_local_mcp_read_tool(source, server_id=server_id) and not mcp_tool_is_readonly(source_row):
+            return False
+
+        has_local_tool = True
+
+    return has_local_tool
+
+
 @dataclass
 class ToolRunSecurityContext:
     """Server-owned integrity state for one agent run."""
@@ -804,6 +1087,19 @@ class ToolRunSecurityContext:
     # Driven by a bearer API token, not a person at a browser. Privileged
     # tools are refused outright and no approval can lift that.
     delegated_credential: bool = False
+    explicit_untrusted_seen: bool = False
+    prompt_external_untrusted_seen: bool = False
+
+    def __post_init__(self) -> None:
+        if self.external_untrusted_context_seen and (
+            not self.external_sources
+            or any(
+                not _is_declared_local_mcp_tool(s)
+                and s not in _SERVER_OWNED_CONTROL_PLANE_SOURCES
+                for s in self.external_sources
+            )
+        ):
+            self.prompt_external_untrusted_seen = True
 
     def observe_messages(self, messages: Iterable[dict]) -> None:
         """Apply server-owned chat scope and promote untrusted prompt context."""
@@ -834,8 +1130,10 @@ class ToolRunSecurityContext:
             if source and source not in self.external_sources:
                 self.external_sources.append(source)
             self.external_untrusted_context_seen = True
+            self.prompt_external_untrusted_seen = True
         if messages_contain_external_untrusted_context(message_list):
             self.external_untrusted_context_seen = True
+            self.prompt_external_untrusted_seen = True
 
     def decision_for(self, tool_name: Any, content: Any = None) -> ToolGateDecision:
         # Checked before the bypasses below, because neither may lift it, and
@@ -858,6 +1156,20 @@ class ToolRunSecurityContext:
         if not self.external_untrusted_context_seen:
             return ToolGateDecision(True)
 
+        # Scoped continuation exception for explicitly declared local MCP tools:
+        # A declared write or read tool on the same MCP server is allowed if
+        # the run's only untrusted context was introduced by declared local
+        # tools on that server, without any explicit/error taint or external
+        # message context.
+        if (
+            not self.prompt_external_untrusted_seen
+            and not self.explicit_untrusted_seen
+            and _is_authorized_local_mcp_continuation(
+                tool_name, self.external_sources, content=content
+            )
+        ):
+            return ToolGateDecision(True)
+
         # Skills and other server-owned descriptors are control-plane metadata
         # rather than external result content; web/document/tool-result taint
         # still gates actions that can mutate state or execute code.
@@ -906,6 +1218,11 @@ class ToolRunSecurityContext:
         if not tool_result_should_arm_gate(tool_name, result, content):
             return
         self.external_untrusted_context_seen = True
+        if isinstance(result, dict) and (
+            result.get("untrusted_content") is True
+            or not tool_result_is_successful(result)
+        ):
+            self.explicit_untrusted_seen = True
         if isinstance(tool_name, str) and tool_name not in self.external_sources:
             self.external_sources.append(tool_name)