Kuberwastaken/claurst · error · anyhow::Error

Unknown MCP server

Error message

Unknown MCP server: {}

What it means

begin_auth() looks up the server's configuration in server_configs before starting an OAuth session. If no config entry exists for the given name, it throws 'Unknown MCP server'. This is a config-table miss — the server may exist but OAuth can only proceed for configured servers.

Solutions

  1. List configured servers (server_configs keys) and confirm the exact name
  2. Fix the server name to match its settings.json entry
  3. Reload/parse the MCP configuration so the server appears in server_configs
  4. Add the server to the configuration if it is genuinely missing

Example fix

// before
hub.begin_auth("github-mcp").await?;
// after
hub.begin_auth("github").await?; // key must match settings.json server name
Defensive patterns

Strategy: validation

Validate before calling

if !hub.configured_server_names().contains(&server_name.to_string()) {
    anyhow::bail!("no MCP config for '{}'; check settings.json", server_name);
}

Try / catch

match hub.begin_auth(server).await {
    Ok(s) => s,
    Err(e) if e.to_string().starts_with("Unknown MCP server") => {
        eprintln!("'{}' not in config; available: {:?}", server, hub.configured_server_names());
        return Ok(());
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: Calling McpHub::begin_auth(server_name) where server_name is not a key in self.server_configs (typo, server defined only at runtime, or configs not loaded yet).

Common situations: Server name typo; calling OAuth on a stdio-only server that was never registered in server_configs; configuration file not reloaded after adding the server; name mismatch between settings.json key and the code.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of Kuberwastaken/claurst@b0637c97ec (2026-09-10). Data as JSON: /api/errors/d2c283c7ba426a02. Report an issue: GitHub.

Appendix: source

Thrown at src-rust/crates/mcp/src/lib.rs:1222

        McpAuthState::Required {
            auth_url: config
                .url
                .clone()
                .unwrap_or_else(|| "(unknown URL)".to_string()),
        }
    }

    /// Initiate OAuth 2.0 + PKCE for an HTTP MCP server.
    pub async fn initiate_auth(&self, server_name: &str) -> anyhow::Result<String> {
        Ok(self.begin_auth(server_name).await?.auth_url)
    }

    /// Build a full OAuth authorization session for an HTTP/SSE MCP server.
    pub async fn begin_auth(&self, server_name: &str) -> anyhow::Result<oauth::McpAuthSession> {
        let config = self
            .server_configs
            .get(server_name)
            .ok_or_else(|| anyhow::anyhow!("Unknown MCP server: {}", server_name))?;

        let base_url = config
            .url
            .as_deref()
            .ok_or_else(|| {
                anyhow::anyhow!(
                    "MCP server '{}' has no URL configured (required for OAuth)",
                    server_name
                )
            })?;

        oauth::begin_mcp_auth(server_name, base_url).await
    }

    /// Run the browser-based OAuth flow and persist the resulting token.
    pub async fn authenticate(&self, server_name: &str) -> anyhow::Result<oauth::McpAuthResult> {
        let config = self
            .server_configs

View on GitHub (pinned to b0637c97ec)