iflytek/astron-agent · error · RuntimeError

No MCP transport candidates were available

Error message

No MCP transport candidates were available

What it means

RuntimeError raised by initialized_mcp_session after every MCP transport candidate fails. The code first tries Streamable HTTP, falls back to legacy SSE, and if both initialization attempts raise (connection refused, timeout, HTTP errors, protocol errors), it gives up with this error.

Solutions

  1. Verify the MCP server URL is correct and the server is running: curl the endpoint to confirm it responds.
  2. Confirm the server supports Streamable HTTP or SSE transport (not stdio-only); switch transport type in tool config if needed.
  3. Check logs just above the error — the 'reason' in the fallback warning names the underlying failure (connection refused/timeout/HTTP status).
  4. Check network/firewall/proxy settings between the plugin and the MCP server; retry after the server is reachable.

Example fix

// before
mcp_url = "http://localhost:9999"  # server not started
session = await initialized_mcp_session(mcp_url)
// after
# start the MCP server first and verify:
#   curl -i http://localhost:9999/mcp
mcp_url = "http://localhost:9999/mcp"
session = await initialized_mcp_session(mcp_url)
Defensive patterns

Strategy: retry

Validate before calling

import httpx
def mcp_endpoint_reachable(url: str) -> bool:
    try:
        return httpx.get(url, timeout=5).status_code < 500
    except httpx.HTTPError:
        return False

Try / catch

try:
    session = await initialized_mcp_session(url)
except RuntimeError as e:
    logger.error("MCP session failed for %s: %s", url, e)
    return ToolResult(error="MCP server unreachable; check URL/transport")

Prevention

When it happens

Trigger: _connect_and_get_tools or _call_mcp_tool call initialized_mcp_session for an MCP server whose endpoint is unreachable, returns non-2xx, is not actually an MCP server, or rejects the initialize handshake over both Streamable HTTP and SSE.

Common situations: MCP server not running or wrong port/URL configured; server deployed behind a proxy stripping SSE headers; server only supports stdio transport while the client tries HTTP; network policy/firewall blocking the endpoint; server version too old for either transport.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/af70488240b880e6. Report an issue: GitHub.

Appendix: source

Thrown at core/plugin/link/service/community/tools/mcp/mcp_transport.py:161

                yield session, candidate
                return
        except Exception as error:
            if initialized:
                raise
            if transport is not MCPTransport.AUTO:
                raise MCPTransportError(phase, candidate, error) from error

            reason = _fallback_reason(error, response_status)
            if candidate is not MCPTransport.STREAMABLE_HTTP or reason is None:
                raise MCPTransportError(phase, candidate, error) from error

            logger.warning(
                "MCP Streamable HTTP initialization failed; falling back to legacy "
                "SSE (reason={})",
                reason,
            )

    raise RuntimeError("No MCP transport candidates were available")

View on GitHub (pinned to 5e758547a8)