Document PyPI+uvx deployment pattern for Python MCP servers

[bryan-anthropic]

Summary

This PR documents the PyPI+uvx deployment pattern for Python MCP servers, which has been in production use (e.g., Braze MCP Server approved Oct 2025) but was previously undocumented in the MCPB specification.

Problem Statement

During MCP server reviews, we identified that:

1. Braze MCP Server (approved, production) uses command: "uvx" with PyPI deployment
2. Zscaler MCP Server (broken) attempted the same pattern but misconfigured it
3. MCPB documentation only describes traditional bundling with command: "python" + bundled dependencies

This created confusion for developers choosing between deployment approaches.

Changes

1. README.md

• ✅ Add comprehensive "PyPI-Based Deployment" section
• ✅ Document when to use PyPI vs traditional bundling
• ✅ Include comparison table with trade-offs
• ✅ Reference Braze MCP Server as production example

2. MANIFEST.md

• ✅ Add Python PyPI+uvx configuration example
• ✅ Document uvx command usage alongside traditional python command
• ✅ Link to README for detailed comparison

3. New Example: examples/pypi-python/

• ✅ Complete working example of PyPI-based bundle
• ✅ Demonstrates uvx command configuration in manifest.json
• ✅ Shows pyproject.toml with [project.scripts] entry point
• ✅ Includes comprehensive README with testing instructions
• ✅ Documents Zscaler MCP fix with correct configuration

PyPI Deployment Pattern Overview

Manifest configuration:

{
  "server": {
    "type": "python",
    "entry_point": "src/package/main.py",
    "mcp_config": {
      "command": "uvx",
      "args": ["--native-tls", "package-name@latest"],
      "env": {
        "API_KEY": "${user_config.api_key}"
      }
    }
  }
}

Benefits:

• Smaller bundle sizes (< 1 MB vs 50+ MB)
• Automatic updates via @latest tag
• Modern Python packaging alignment
• Developers can push updates without resubmitting bundles

Trade-offs:

• Requires users to install uv tool
• Needs internet connection at first launch

Production Usage

Braze MCP Server has been using this pattern successfully:

• Bundle size: ~800 KB (vs potential 50+ MB with bundled deps)
• Published to PyPI: braze-mcp-server
• Repository: https://github.com/braze-inc/braze_mcp_server

Testing

• Verified Braze MCP Server manifest structure
• Confirmed Zscaler package published to PyPI: https://pypi.org/project/zscaler-mcp/
• Created working example with proper configuration
• Documented both deployment approaches with clear comparison

Files Changed

 MANIFEST.md                                        |  26 ++-
 README.md                                          | 210 ++++++++++++++++++++
 examples/pypi-python/README.md                     | 177 ++++++++++++++++
 examples/pypi-python/ZSCALER_FIX.md                | 217 ++++++++++++++++++++
 examples/pypi-python/manifest.json                 |  66 +++++++
 examples/pypi-python/pyproject.toml                |  38 ++++
 examples/pypi-python/src/example_pypi_mcp/__init__.py |   3 +
 examples/pypi-python/src/example_pypi_mcp/main.py  |  97 +++++++++
 8 files changed, 833 insertions(+), 1 deletion(-)

For Reviewers

This PR does NOT change:

• Existing traditional bundling documentation
• Schema definitions or validation
• CLI tooling behavior

It ADDS:

• Documentation for an alternative deployment pattern already in production
• Clear guidance on when to use each approach
• Complete working example for reference

Related Issues

This addresses confusion seen in:

• Braze MCP Server review (approved Oct 2025)
• Zscaler MCP Server review (broken due to manifest/PyPI mismatch)
• Multiple developer questions about bundle size optimization