autogen - ✅(Solved) Fix Improve error messages for missing MCP server dependencies in AssistantAgent [1 pull requests, 2 comments, 2 participants]

autogen2026-03-03 06:28:11

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

microsoft/autogen#7337•Fetched 2026-04-08 00:39:51

View on GitHub

Comments

Participants

Timeline

Reactions

Author

KlementMultiverse

Participants

KlementMultiverse

Rishirandhawa

Timeline (top)

commented ×2closed ×1cross-referenced ×1

Error Message

MCPConnectionError: Could not connect to MCP server 'playwright' at localhost:5000.

This usually means the server is not installed or running.

To install: npm install -g @playwright/mcp@latest To start: mcp-playwright (or see https://...)

If already installed, verify the server is running and accessible.

Root Cause

The MCP integration pattern is becoming a primary way users extend AutoGen agents with tools. The README explicitly documents this workflow, but the error experience breaks the documented flow. New users waste time debugging network/import issues when the solution is a single npm command.

Fix Action

Fixed

Fixed by PR: Improve MCP startup errors for missing server dependencies (https://github.com/microsoft/autogen/pull/7339)

PR fix notes

PR #7339: Improve MCP startup errors for missing server dependencies

Repository: microsoft/autogen
Author: Rishirandhawa
State: open | merged: False
Link: https://github.com/microsoft/autogen/pull/7339

Description (problem / solution / changelog)

Summary

add MCP startup error formatting in McpWorkbench.list_tools() to surface actionable guidance instead of opaque actor crashes
include specific Playwright MCP install guidance when the configured stdio command targets @playwright/mcp
include command-not-found guidance for missing stdio executables
add tests covering both new startup error paths

Why

AssistantAgent MCP workflows often fail with generic connection errors when MCP server dependencies are missing. This makes the README quickstart hard to debug, especially for Playwright MCP setup.

Fixes #7337

Validation

python3 -m ruff check python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py python/packages/autogen-ext/tests/tools/test_mcp_workbench_warnings_and_errors.py
uv run --package autogen-ext --extra mcp pytest -q packages/autogen-ext/tests/tools/test_mcp_workbench_warnings_and_errors.py -k "playwright_dependency_hint or missing_stdio_command or list_tools_actor_none_after_start"

Changed files

python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py (modified, +80/-2)
python/packages/autogen-ext/tests/tools/test_mcp_workbench_warnings_and_errors.py (modified, +43/-1)

Code Example

MCPConnectionError: Could not connect to MCP server 'playwright' at localhost:5000.

This usually means the server is not installed or running.

To install: npm install -g @playwright/mcp@latest
To start: mcp-playwright (or see https://...)

If already installed, verify the server is running and accessible.

RAW_BUFFERClick to expand / collapse

Problem

When users follow the MCP Server quickstart example in the README and run code without installing the required MCP server (e.g., @playwright/mcp), they encounter cryptic error messages that don't clearly indicate the root cause or remediation steps.

For example, attempting to use Playwright-based browsing without running npm install -g @playwright/mcp@latest first results in generic connection or import errors rather than a helpful message pointing to the missing installation step.

Why This Matters

Current Behavior

User runs MCP Server quickstart code
MCP server is not installed or running
Error message is generic (connection timeout, module not found, etc.)
User has no clear path to fix the issue

Expected Behavior

When an agent attempts to connect to an MCP server and the connection fails, the error message should:

Explicitly state which MCP server is missing or unreachable
Provide the exact installation command (e.g., npm install -g @playwright/mcp@latest)
Suggest checking if the server is running locally
Link to the relevant documentation section

Example

MCPConnectionError: Could not connect to MCP server 'playwright' at localhost:5000.

This usually means the server is not installed or running.

To install: npm install -g @playwright/mcp@latest
To start: mcp-playwright (or see https://...)

If already installed, verify the server is running and accessible.

Suggested Implementation

Enhance error handling in autogen_agentchat/agents/assistant_agent.py where MCP connections are initialized. Check the connection attempt and catch connection/timeout errors, then provide context-specific guidance based on which server was being connected to.

Consider maintaining a small registry mapping MCP server names to installation instructions (e.g., in autogen_ext/mcp/ or similar).

Contributed by Klement Gunndu

extent analysis

Fix Plan

To address the issue, we need to enhance error handling in the autogen_agentchat/agents/assistant_agent.py file. Here are the steps:

Catch connection and timeout errors when initializing MCP connections
Provide context-specific guidance based on the MCP server being connected to
Maintain a registry mapping MCP server names to installation instructions

Example Code

import logging

# Registry mapping MCP server names to installation instructions
mcp_server_registry = {
    'playwright': {
        'installation_command': 'npm install -g @playwright/mcp@latest',
        'start_command': 'mcp-playwright',
        'documentation_link': 'https://...'
    }
}

def connect_to_mcp_server(server_name, host, port):
    try:
        # Attempt to connect to the MCP server
        # ...
    except ConnectionError:
        # Catch connection errors and provide context-specific guidance
        error_message = f"MCPConnectionError: Could not connect to MCP server '{server_name}' at {host}:{port}."
        installation_command = mcp_server_registry.get(server_name, {}).get('installation_command')
        start_command = mcp_server_registry.get(server_name, {}).get('start_command')
        documentation_link = mcp_server_registry.get(server_name, {}).get('documentation_link')
        
        if installation_command:
            error_message += f"\nTo install: {installation_command}"
        if start_command:
            error_message += f"\nTo start: {start_command}"
        if documentation_link:
            error_message += f"\nSee {documentation_link} for more information."
        
        error_message += "\nIf already installed, verify the server is running and accessible."
        logging.error(error_message)
        raise MCPConnectionError(error_message)

class MCPConnectionError(Exception):
    pass

Verification

To verify that the fix worked, run the MCP Server quickstart code without installing the required MCP server and check that the error message provides clear guidance on how to install and start the server.

Extra Tips

Make sure to update the mcp_server_registry dictionary with the correct installation commands and documentation links for each MCP server.
Consider adding additional error handling for other types of errors that may occur when connecting to the MCP server.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#api #ssr #installation #tensor shape #autograd error #mixed precision #training loop #device allocation #model download

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Data

Security

Network

Code

UI/UX

Text

System

Multimedia

Protocol

API

Engineering

autogen - ✅(Solved) Fix Improve error messages for missing MCP server dependencies in AssistantAgent [1 pull requests, 2 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Fix Action

Fixed

PR fix notes

PR #7339: Improve MCP startup errors for missing server dependencies

Description (problem / solution / changelog)

Summary

Why

Validation

Changed files

Code Example

Problem

Why This Matters

Current Behavior

Expected Behavior

Example

Suggested Implementation

extent analysis

Fix Plan

Example Code

Verification

Extra Tips

Still need to ship something?

TRENDING

autogen - ✅(Solved) Fix Improve error messages for missing MCP server dependencies in AssistantAgent [1 pull requests, 2 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Fix Action

Fixed

PR fix notes

PR #7339: Improve MCP startup errors for missing server dependencies

Description (problem / solution / changelog)

Summary

Why

Validation

Changed files

Code Example

Problem

Why This Matters

Current Behavior

Expected Behavior

Example

Suggested Implementation

extent analysis

Fix Plan

Example Code

Verification

Extra Tips

Still need to ship something?

RELATED_DISCOVERY

TRENDING