iflytek/astron-agent · error · GetMcpPluginExc

LIST_MCP_PLUGIN_URL is not set

Error message

LIST_MCP_PLUGIN_URL is not set

What it means

GetMcpPluginExc raised in McpPlugin.query_servers (mcp.py:157). Before listing MCP servers, the code reads LIST_MCP_PLUGIN_URL from the environment; if unset or empty it raises 'LIST_MCP_PLUGIN_URL is not set' (code 40026). It is a deployment/configuration failure, raised before any network I/O.

Solutions

  1. Set LIST_MCP_PLUGIN_URL (e.g. http://mcp-plugin:8080/list) in the agent service environment and restart.
  2. Add it to the compose/Helm config alongside RUN_MCP_PLUGIN_URL so both MCP endpoints are provisioned together.
  3. Add a boot-time check that asserts both MCP URL env vars exist when MCP tools are enabled.

Example fix

// before (helm values)
agent:
  env:
    RUN_MCP_PLUGIN_URL: http://mcp-plugin:8080/run
// after
agent:
  env:
    RUN_MCP_PLUGIN_URL: http://mcp-plugin:8080/run
    LIST_MCP_PLUGIN_URL: http://mcp-plugin:8080/list
Defensive patterns

Strategy: validation

Validate before calling

list_url = os.getenv("LIST_MCP_PLUGIN_URL")
if not list_url:
    raise RuntimeError("LIST_MCP_PLUGIN_URL must be set to build MCP tools")

Try / catch

try:
    servers = await mcp_plugin.query_servers(span)
except GetMcpPluginExc as e:
    if "not set" in str(e):
        logger.critical("MCP listing not configured: %s", e)
    raise

Prevention

When it happens

Trigger: Building the agent's tool list (build_tools -> query_servers) in a process where LIST_MCP_PLUGIN_URL was never set.

Common situations: Missing env entry in docker compose / Helm values, .env file not mounted, variable name typo, or MCP plugin feature enabled without its endpoint configured.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at core/agent/service/plugin/mcp.py:157

                mcp_plugins.append(mcp_plugin)
        return mcp_plugins

    async def query_servers(self, span: Span) -> list[dict]:
        with span.start("QueryServers") as sp:
            data = {
                "sid": sp.sid,
                "mcp_server_ids": self.mcp_server_ids,
                "mcp_server_urls": self.mcp_server_urls,
            }
            sp.add_info_events(
                attributes={
                    "mcp-query-servers-inputs": json.dumps(data, ensure_ascii=False)
                }
            )
            try:
                list_url = os.getenv("LIST_MCP_PLUGIN_URL")
                if not list_url:
                    raise GetMcpPluginExc("LIST_MCP_PLUGIN_URL is not set")
                async with aiohttp.ClientSession() as session:
                    timeout = aiohttp.ClientTimeout(total=40)
                    async with session.post(
                        list_url,
                        json=data,
                        timeout=timeout,
                    ) as response:
                        response.raise_for_status()
                        if response.status == 200:
                            resp = await response.json()
                            sp.add_info_events(
                                attributes={
                                    "mcp-plugin-list-outputs": json.dumps(
                                        resp, ensure_ascii=False
                                    )
                                }
                            )
                        else:

View on GitHub (pinned to 5e758547a8)