{"slug": "uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name", "title": "uvx fails on a Python MCP server whose command name differs from its PyPI name", "summary": "The maintainer of aisync, a local CLI for multi-agent context management that ships an MCP server, found that `uvx aisync-cli` fails because uvx looks for an executable matching the PyPI package name while the package installs a command called `aisync`. In version 0.2.11 the maintainer added a console script named after the package and documented a registry `server.json` that uses `--with \"mcp>=2.3,<3\"` and a positional `mcp` argument so uvx can start the server, with `mcp-publisher validate` confirming the file is valid.", "body_md": "aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it, and it ships an MCP server (`aisync mcp`). While preparing it for the official MCP registry I found that `uvx <package-name>` failed for it, and the reason applies to any Python MCP server whose command name differs from its PyPI name. This post is what I ran and what I did not run.\n\nThe PyPI package is `aisync-cli`; the command it installs is `aisync`. With `HOME` pointed at a temp directory (so nothing from my real setup was reused), on 0.2.10:\n\n```\nuvx aisync-cli@0.2.10 --version\nAn executable named `aisync-cli` is not provided by package `aisync-cli`.\nThe following executables are available:\n- aisync\n\nUse `uvx --from aisync-cli aisync` instead.\n```\n\nExit code 1. `uvx <name>` looks for an executable with the same name as the package. A registry entry that names `aisync-cli` as its PyPI identifier points at exactly that form.\n\nThe MCP SDK is an optional extra in this package (`aisync-cli[mcp]`). With the right executable but no extra:\n\n```\nuvx --from aisync-cli@0.2.10 aisync mcp\n```\n\nIt exits with code 2 and prints `error: the MCP server needs the official SDK: pip install 'aisync-cli[mcp]' (mcp>=2.3)`. With the extra (`--from 'aisync-cli[mcp]@0.2.10'`) the server answers an `initialize` request and exits cleanly when stdin closes.\n\nTwo small changes in 0.2.11:\n\n`uvx aisync-cli` finds an executable: in `pyproject.toml`, `aisync-cli = \"ai_sync.cli:main\"` next to `aisync = ...`.`--with \"mcp>=2.3,<3\"`, plus the positional argument `mcp`.\n\n```\nuvx aisync-cli@0.2.11 --version\n# aisync 0.2.11\nuvx --with \"mcp>=2.3,<3\" aisync-cli@0.2.11 mcp\n# answers initialize, exit 0\n```\n\nBoth ran in a temp HOME against the version published on PyPI.\n\nThe registry's `server.json` for a PyPI package, as I wrote it:\n\n```\n{\n  \"name\": \"io.github.MaxonT/aisync\",\n  \"version\": \"0.2.11\",\n  \"packages\": [{\n    \"registryType\": \"pypi\",\n    \"identifier\": \"aisync-cli\",\n    \"version\": \"0.2.11\",\n    \"runtimeHint\": \"uvx\",\n    \"runtimeArguments\": [{\"type\": \"named\", \"name\": \"--with\", \"value\": \"mcp>=2.3,<3\"}],\n    \"packageArguments\": [{\"type\": \"positional\", \"value\": \"mcp\"}],\n    \"transport\": {\"type\": \"stdio\"}\n  }]\n}\n```\n\n(`$schema`, title, description and repository are left out here.) The registry checks ownership of a PyPI package by looking for `mcp-name: io.github.MaxonT/aisync` in the package README, which becomes the PyPI description. I put it in an HTML comment in `README.md` and read it back from the PyPI JSON after the release. `mcp-publisher validate` printed `server.json is valid`; it validates against the live registry, so it is a stronger check than the JSON schema alone.\n\n`runtimeHint`, `runtimeArguments` and `packageArguments`. I read the schema descriptions and assumed the arguments go before the package name and the package arguments after it. The local runs above use that shape; no real client was involved.\nRun `uvx <your-pypi-name> --version` in a clean directory. If the executable name differs, add a console script with the package name, and check whether your server needs an extra before `uvx` can start it.\n\n`pip install aisync-cli`\nThis post and the test runs were written and tested by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.", "url": "https://wpnews.pro/news/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name", "canonical_source": "https://dev.to/maxont/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name-13do", "published_at": "2026-11-16 14:17:20+00:00", "updated_at": "2026-11-16 14:22:11.786461+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["aisync", "PyPI", "uvx", "MCP registry", "Claude Code", "MaxonT"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name", "markdown": "https://wpnews.pro/news/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name.md", "text": "https://wpnews.pro/news/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name.txt", "jsonld": "https://wpnews.pro/news/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name.jsonld"}}