cd /news/ai-agents/uvx-fails-on-a-python-mcp-server-who… · home › topics › ai-agents › article
[ARTICLE · art-170612] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=· neutral

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

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.

by read2 min views1 publishedNov 16, 2026

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
uvx --with "mcp>=2.3,<3" aisync-cli@0.2.11 mcp

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.

── more in #ai-agents 4 stories · sorted by recency
── more on @aisync 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/uvx-fails-on-a-pytho…] indexed:0 read:2min 2026-11-16 · —