iflytek/astron-agent · error · RunMcpPluginExc

RUN_MCP_PLUGIN_URL is not set

Error message

RUN_MCP_PLUGIN_URL is not set

What it means

RunMcpPluginExc raised in McpPluginRunner.run (mcp.py:44). Before POSTing to the MCP plugin runner, the code reads the RUN_MCP_PLUGIN_URL environment variable; if it is unset (or empty), it raises immediately with 'RUN_MCP_PLUGIN_URL is not set' (code 40027). This is a pure deployment/configuration error: no HTTP call is ever made.

Solutions

  1. Set RUN_MCP_PLUGIN_URL (e.g. http://mcp-plugin:8080/run) in the agent service's environment and restart the service.
  2. In docker: add it to the core/agent environment section of docker compose or the .env file; in Helm: set it in the agent deployment values.
  3. Add a startup-time fail-fast check that validates required plugin URL env vars so the misconfiguration is caught at boot instead of at first tool call.

Example fix

// before (docker-compose)
agent:
  environment:
    - LIST_MCP_PLUGIN_URL=http://mcp-plugin:8080/list
// after
agent:
  environment:
    - LIST_MCP_PLUGIN_URL=http://mcp-plugin:8080/list
    - RUN_MCP_PLUGIN_URL=http://mcp-plugin:8080/run
Defensive patterns

Strategy: validation

Validate before calling

run_url = os.getenv("RUN_MCP_PLUGIN_URL")
if not run_url:
    raise RuntimeError("RUN_MCP_PLUGIN_URL must be set before invoking MCP tools")

Try / catch

try:
    result = await runner.run(action_input, span)
except RunMcpPluginExc as e:
    if "not set" in str(e):
        logger.critical("MCP plugin not configured: %s", e)
    raise

Prevention

When it happens

Trigger: Invoking any MCP server tool while the agent process was started without RUN_MCP_PLUGIN_URL in its environment.

Common situations: Docker Compose / Helm values missing the env var, .env not mounted into the agent container, typo in the variable name, or a fresh deployment where the MCP plugin service endpoint was never 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/a18da5862433de60. Report an issue: GitHub.

Appendix: source

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

    async def run(self, action_input: dict, span: Span) -> Any:
        with span.start("Run") as sp:
            start_time = int(round(time.time() * 1000))
            data = {
                "mcp_server_id": self.server_id,
                "mcp_server_url": self.server_url,
                "tool_name": self.name,
                "tool_args": action_input,
                "sid": sp.sid,
            }
            sp.add_info_events(
                attributes={
                    "mcp-plugin-run-inputs": json.dumps(data, ensure_ascii=False)
                }
            )
            try:
                run_url = os.getenv("RUN_MCP_PLUGIN_URL")
                if not run_url:
                    raise RunMcpPluginExc("RUN_MCP_PLUGIN_URL is not set")
                async with aiohttp.ClientSession() as session:
                    timeout = aiohttp.ClientTimeout(
                        total=int(os.getenv("MCP_CALL_TIMEOUT", "90"))
                    )
                    async with session.post(
                        run_url,
                        json=data,
                        headers={"Content-Type": "application/json"},
                        timeout=timeout,
                    ) as response:
                        response.raise_for_status()
                        if response.status == 200:
                            resp = await response.json()
                            sp.add_info_events(
                                attributes={
                                    "mcp-plugin-run-outputs": json.dumps(
                                        resp, ensure_ascii=False
                                    )

View on GitHub (pinned to 5e758547a8)