resource URI ' ' is ambiguous across MCP servers: ; pass…

Error message

resource URI '{uri}' is ambiguous across MCP servers: {}; pass the legacy server parameter to disambiguate

What it means

When a resource URI is advertised by two or more running MCP servers, read_resource_by_uri cannot determine which server to read from and refuses to guess. The error lists the conflicting servers and instructs the caller to pass the legacy server parameter to disambiguate.

Solutions

Call the read with the legacy disambiguation: pass the explicit server name (read_resource(server, uri)) chosen from the server list in the error message.
Change one server's advertised URIs so namespaces no longer overlap, then retry URI-only resolution.
Disconnect or remove one of the conflicting servers if it is redundant.

Example fix

// before
manager.read_resource_by_uri("docs://api/intro")  // ambiguous: docs_a, docs_b
// after
manager.read_resource("docs_b", "docs://api/intro")

Defensive patterns

Strategy: validation

Validate before calling

fn owning_servers(manager: &McpManager, uri: &str) -> Vec<String> {
    manager.clients.keys().filter(|s|
        manager.list_resources(s).map(|rs| rs.iter().any(|r| r.uri == uri)).unwrap_or(false)
    ).cloned().collect()
}
// if owning_servers(...).len() > 1, require an explicit server choice before reading

Try / catch

match manager.read_resource_by_uri(uri) {
    Err(e) if e.to_string().contains("is ambiguous across MCP servers") => {
        let server = config.default_resource_server
            .ok_or_else(|| anyhow!("{e}; configure a default server"))?;
        manager.read_resource(&server, uri)
    }
    other => other,
}

Prevention

Namespace resource URIs per server so the same URI never appears twice.
Keep a user/config-level default server for shared URI schemes.
Detect overlapping URIs at connect time and surface a config warning.

When it happens

Trigger: Calling read_resource_by_uri(uri) where matches spans multiple server names after matching the URI against each server's advertised resources.

Common situations: Two MCP servers advertise the same standard URI scheme (e.g., both expose file:// or a shared docs:// namespace); connecting a second server whose resource URIs overlap the first; migrating servers without deduplicating URIs.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/60be5866dfa5c09f. Report an issue: GitHub.

Appendix: source

Thrown at crates/mcp/src/lib.rs:599

                matches.push(server_name.clone());
            }
        }

        match matches.len() {
            1 => self.read_resource(&matches[0], uri),
            0 => {
                // Preserve the pre-standard URI convention for clients whose
                // server does not implement resources/list.
                if let Some(server_name) = parse_server_from_uri(uri)
                    && self.clients.contains_key(&server_name)
                {
                    return self.read_resource(&server_name, uri);
                }
                bail!("resource URI '{uri}' was not advertised by any running MCP server")
            }
            _ => {
                matches.sort();
                bail!(
                    "resource URI '{uri}' is ambiguous across MCP servers: {}; pass the legacy \
                     server parameter to disambiguate",
                    matches.join(", ")
                )
            }
        }
    }

    /// Generate sandbox state update notices for all registered servers.
    pub fn update_sandbox_state(&self, sandbox_mode: &str, cwd: &str) -> Result<Vec<Value>> {
        let mut notices = Vec::new();
        for server_name in self.configs.keys() {
            notices.push(json!({
                "server_name": server_name,
                "method": "codex/sandbox-state/update",
                "params": {
                    "sandbox_mode": sandbox_mode,
                    "cwd": cwd

View on GitHub (pinned to 73e0f67d83)