mcp-multi-poc

mcp-multi-poc

PoC for serving multiple MCP servers from a single PyPI package, usingsubcommands for server selection and optional extras for on-demand dependencies.Stands in for the Couchbase MCP monorepo question (alpha = operational,beta = analytics, tabulate = the analytics SDK — chosen because it is outsidefastmcp's transitive dependency tree; httpx and pyyaml are not, and silentlydefeat the extras guard).

What this PoC must answer

Findings so far (2026-07-31)

• Q1 — multiple entries per PyPI package: YES. mcp-multi-poc-alpha publishedagainst the shared package.
• Q2 — multiple mcp-name comments in one README: YES (alpha validated withthree comments present).
• Q3 — extras in identifier: NO, but expressible via runtimeArguments.Extras in the identifier fail the literal PyPI lookup —PyPI package 'mcp-multi-poc[beta]' not found (status: 404). Fallbackworks: mcp-multi-poc-beta published successfully with plainidentifier: mcp-multi-poc + runtimeArguments: --from "mcp-multi-poc[beta]"(live in the registry, verified via the /v0/servers API).
• Q5a — differently-named console script as identifier: NO (confirmed onpublish). Same 404 mechanism ('mcp-multi-poc-beta' not found) — theregistry validates the identifier as a real PyPI package before anything else.
• Q5b — script name as positional runtimeArgument: YES, published.io.github.nithishr/mcp-multi-poc-beta-script is live (published2026-07-31, after trimming description to the 100-char limit — the onlyvalidation hiccup). Locally, uvx --from 'mcp-multi-poc[beta]' mcp-multi-poc-beta mcp-multi-poc completes the MCP initialize handshake —the trailing identifier is silently ignored because main() never parsesargv. Caveats: only safe when the entrypoint tolerates stray argv (clickneeds ignore_unknown_options + allow_extra_args or a dummy optionalargument); depends on clients preserving runtimeArguments order — theleast-exercised metadata path; registry UIs show the identifier as therunnable. For production script-per-server, prefer a shim package perscript (identifier == script name, no runtimeArguments at all).
• Registry validation limits discovered: description ≤ 100 chars;identifier must be a literal, existing PyPI package (extras rejected);runtimeArguments/packageArguments contents are NOT validated.

Local smoke test (before publishing anything)

cd mcp-registry-poc
uv venv && uv pip install -e .
mcp-multi-poc alpha          # starts alpha on stdio (Ctrl+C to exit)
mcp-multi-poc beta           # must FAIL with the friendly extras message
uv pip install -e ".[beta]"
mcp-multi-poc beta           # now starts
mcp-multi-poc                # bare command runs alpha (backward-compat check)
mcp-multi-poc-beta           # Option 1 script works locally once extra installed

uvx behavior (after publishing to PyPI):

uvx mcp-multi-poc alpha                  # base only
uvx "mcp-multi-poc[beta]" beta           # extras via uvx — key UX under test
uvx --from "mcp-multi-poc[beta]" mcp-multi-poc-beta   # Option 1 fallback form

Publish steps (manual, in order)

1. If mcp-multi-poc is taken on PyPI, pick another name and rename consistently(pyproject name, [project.scripts], both server.json identifiers).
2. Build and publish to real PyPI (registry validation fetches from pypi.org;TestPyPI will not work): uv build && uv publish.
3. Install mcp-publisher and log in:mcp-publisher login github (interactive) — must match the io.github.<username> namespace.
4. Publish the entries:mcp-publisher publish server.alpha.json, ... server.beta.json, and... server.beta-script.json — the last one is expected to fail validation;record the exact error (if the CLI expects the file at ./server.json, copyeach into place first).
5. Verify via the registry API:curl "https://registry.modelcontextprotocol.io/v0/servers?search=mcp-multi-poc"
6. Configure both servers in a client from the registry metadata and callecho (alpha) and make_table (beta).
7. Record results per question above, then deprecate/delete the PoC entries.

Q4 — testing the published entries from a client

Most clients don't install directly from the official registry yet, so Q4splits in two: (a) does the spec-mandated command construction(uvx <runtimeArguments> <identifier> <packageArguments>) produce a workingserver, and (b) does a registry-consuming client reproduce that construction.

1. Fetch what was actually published and check the packages block:curl "https://registry.modelcontextprotocol.io/v0/servers?search=mcp-multi-poc"
2. MCP Inspector — interactive tool calls against the hand-assembled command:

   npx @modelcontextprotocol/inspector uvx mcp-multi-poc alpha
   npx @modelcontextprotocol/inspector uvx --from "mcp-multi-poc[beta]" mcp-multi-poc beta
   

3. Claude Code — same commands as stdio servers, then call echo / make_table:

   claude mcp add poc-alpha -- uvx mcp-multi-poc alpha
   claude mcp add poc-beta -- uvx --from "mcp-multi-poc[beta]" mcp-multi-poc beta
   

   (For Claude Desktop, the equivalent claude_desktop_config.json entries:)

   {
     "mcpServers": {
       "poc-alpha": { "command": "uvx", "args": ["mcp-multi-poc", "alpha"] },
       "poc-beta":  { "command": "uvx", "args": ["--from", "mcp-multi-poc[beta]", "mcp-multi-poc", "beta"] }
     }
   }
   

4. Registry-native install (the real (b) test): VS Code's MCP servergallery is backed by the official registry — search for mcp-multi-pocthere and install; this exercises whether a client assemblesruntimeArguments + identifier + packageArguments on its own. Entries maylag or be curated before appearing.

Steps 2–3 only prove (a); only step 4 (or another registry-consuming client)proves (b), which is what the beta/beta-script entries actually depend on.