# uvx fails on a Python MCP server whose command name differs from its PyPI name

> Source: <https://dev.to/maxont/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name-13do>
> Published: 2026-11-16 14:17:20+00:00

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.

The 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:

```
uvx aisync-cli@0.2.10 --version
An executable named `aisync-cli` is not provided by package `aisync-cli`.
The following executables are available:
- aisync

Use `uvx --from aisync-cli aisync` instead.
```

Exit 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.

The MCP SDK is an optional extra in this package (`aisync-cli[mcp]`). With the right executable but no extra:

```
uvx --from aisync-cli@0.2.10 aisync mcp
```

It 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.

Two small changes in 0.2.11:

`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`.

```
uvx aisync-cli@0.2.11 --version
# aisync 0.2.11
uvx --with "mcp>=2.3,<3" aisync-cli@0.2.11 mcp
# answers initialize, exit 0
```

Both ran in a temp HOME against the version published on PyPI.

The registry's `server.json` for a PyPI package, as I wrote it:

```
{
  "name": "io.github.MaxonT/aisync",
  "version": "0.2.11",
  "packages": [{
    "registryType": "pypi",
    "identifier": "aisync-cli",
    "version": "0.2.11",
    "runtimeHint": "uvx",
    "runtimeArguments": [{"type": "named", "name": "--with", "value": "mcp>=2.3,<3"}],
    "packageArguments": [{"type": "positional", "value": "mcp"}],
    "transport": {"type": "stdio"}
  }]
}
```

(`$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.

`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.
Run `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.

`pip install aisync-cli`
This 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.
