ComposioHQ/composio · error · ValidationError

Failed to list MCP servers

Error message

Failed to list MCP servers

What it means

Thrown when the Composio backend call to list MCP server configurations fails for any reason (network, auth, API error) while executing MCP.list(). The original exception is chained via `raise ... from e`, so the underlying cause is preserved. It surfaces as a ValidationError even though the root cause is usually not validation-related.

Solutions

1. Check the chained exception (`except ValidationError as e: print(e.__cause__)`) to see the real API/network error
2. Verify your API key is set and valid (Composio(api_key=...))
3. Upgrade the composio package to the latest version in case the response schema changed
4. Retry with no filters to confirm the base endpoint works

Example fix

// before
servers = composio.mcp.list()

# after
try:
    servers = composio.mcp.list()
except ValidationError as e:
    logger.error("list failed: %s", e.__cause__)
    raise

# none possible client-side beyond auth check
from composio.exceptions import ComposioClientError
assert composio.api_key, 'API key required'

try:
    servers = composio.mcp.list()
except ValidationError as e:
    logger.error('mcp.list failed: %s', e.__cause__)
    raise

When it happens

Trigger: Calling composio.mcp.list() (optionally with page/page_no/limit/toolkits filters) when the API request raises — e.g. invalid API key, network outage, 5xx from backend, or an unexpected response shape that breaks pagination parsing.

Common situations: Expired or missing COMPOSIO_API_KEY, stale SDK version against a changed backend response schema, running in an environment without network access to api.composio.dev.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Failed to delete MCP server
• Failed to update MCP server
• Failed to fetch file from URL
• Failed to parse MCP server instance
• Failed to retrieve MCP server

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/4397631742db01c9. Report an issue: GitHub.

Appendix: source

Thrown at python/composio/core/models/mcp.py:290

                toolkits=none_to_omit(toolkits),
                auth_config_ids=none_to_omit(auth_config_ids),
                name=none_to_omit(name),
                order_by=none_to_omit(order_by),
                order_direction=none_to_omit(order_direction),
            )

            items = (
                response.items if hasattr(response, "items") and response.items else []
            )

            return MCPListResponse(
                items=items,
                current_page=getattr(response, "current_page", page_no or 1),
                total_pages=getattr(response, "total_pages", 1),
            )

        except Exception as e:
            raise ValidationError("Failed to list MCP servers") from e

    def get(self, server_id: str):
        """
        Retrieve detailed information about a specific MCP server/config.

        :param server_id: The unique identifier of the MCP server/config
        :return: Complete MCP server information

        Example:
            >>> server = composio.experimental.mcp.get('mcp_12345')
            >>>
            >>> print(server['name'])  # "My Personal MCP Server"
            >>> print(server['allowed_tools'])  # ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
            >>> print(server['toolkits'])  # ["github", "slack"]
            >>> print(server['server_instance_count'])  # 3
        """
        try:
            response = self._client.mcp.retrieve(server_id)

View on GitHub (pinned to 64b1b85502)