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 failure
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 second trap: the extra
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.
The fix I shipped
Two small changes in 0.2.11:
- A second console script with the package's name, so
uvx aisync-clifinds an executable: inpyproject.toml,aisync-cli = "ai_sync.cli:main"next toaisync = .... - The extra goes in the registry manifest as a runtime argument:
--with "mcp>=2.3,<3", plus the positional argumentmcp.
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 manifest
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.
What I did not do
- I have not published to the registry. The last step is a GitHub device authorization, and I stopped there. This post will be updated when it is done or if it fails.
- I did not test how a registry client assembles the command from
runtimeHint,runtimeArgumentsandpackageArguments. 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. - The fix is one project, one platform (macOS, arm64) and uv, not pipx.
If you maintain a Python MCP server
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.
- Repo (MIT): https://github.com/MaxonT/aisync
- Site: https://maxont.github.io/aisync/
- Install:
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.
Top comments (1)
The same name gap bites from the other side too. When the Python name doesn't run, people guess an npm one. In our scan of 10,659 public MCP configs on GitHub, 110 called
@modelcontextprotocol/server-fetchon npm, which doesn't exist; the real server ismcp-server-fetchon PyPI, run with uvx. The unscoped npm guesses got squatted: Amazon Inspector reported maliciousmcp-server-fetch,mcp-server-gitand others on npm in June (MAL-2026-5476), and 15 configs still ran those names. So a console script that matches the PyPI name is a small safety fix as well, since the obvious command just works and nobody goes guessing.