mcp-swagger-ui

Swagger UI style documentation for MCP FastMCP servers.

Features

Given an mcp.server.fastmcp.FastMCP instance, this package:

• inspects registered tools, prompts, resources, and resource templates
• generates an OpenAPI-like JSON document
• serves the same Swagger UI style as FastAPI /docs
• shows tool and prompt arguments directly in Swagger parameter lists
• highlights required vs optional arguments in generated docs
• supports optional auth for docs endpoints

Installation

pip install mcp-swagger-ui

For local development:

cd mcp_swagger_ui
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

Quickstart

from fastapi import FastAPI, HTTPException, Header
from mcp.server.fastmcp import FastMCP
from mcp_swagger_ui import mount_mcp_docs

# your FastMCP instance
mcp = FastMCP("My MCP Server")

app = FastAPI()

def docs_auth(x_api_key: str | None = Header(default=None)) -> None:
    if x_api_key != "secret-docs-key":
        raise HTTPException(status_code=401, detail="Unauthorized")

mount_mcp_docs(
    app,
    mcp,
    mount_path="/mcp-docs",
    title="My MCP Server Docs",
    auth_dependency=docs_auth,  # optional
)

Then open:

• http://localhost:8000/mcp-docs
• http://localhost:8000/mcp-docs/openapi.json

What The Docs Show

The generated docs are discoverability-focused and currently document:

• tool descriptions
• prompt descriptions
• argument names, types, defaults, and required status
• response schema summaries when available

Tools, prompts, and resources are grouped by Swagger tags, while the displayed paths use only the item names such as /search_users or /summarize_text.

Testing

This project includes a pytest suite with coverage enforcement.

• minimum coverage: 90%
• configured in: pyproject.toml
• command guide: TESTING.md

Release Process

This repository follows an automated open-source release flow:

• pull requests run CI
• release preparation happens in a maintainer-controlled release branch
• release PRs must include version and changelog updates
• publishing to PyPI happens only from a pushed v* tag that matches the package version on master

Contributor guidance:

• keep user-facing changes documented in the PR and in docs when needed
• do not manually edit versions for normal feature PRs unless the work is explicitly release preparation

Maintainer guides:

• release process details: RELEASING.md
• test and local commands: TESTING.md

API

• mount_mcp_docs(app, mcp, mount_path="/mcp-docs", title="MCP Docs", version="1.0.0", auth_dependency=None) -> None
• create_docs_router(mcp, title="MCP Docs", version="1.0.0", openapi_path="/openapi.json", auth_dependency=None) -> APIRouter

Compatibility

• FastMCP API alignment:
  • Uses official server methods first: list_tools(), list_prompts(), list_resources(), list_resource_templates()
  • Handles async and sync method returns
  • Uses converter helpers (to_mcp_tool(), to_mcp_prompt(), to_mcp_resource()) when available
• A generic fallback introspection path is still present for compatibility with FastMCP-adjacent objects.
• The generated schema is OpenAPI-like and focused on discoverability/documentation.
• Tool execution against an already-mounted MCP JSON-RPC endpoint is not implemented in this package yet.

Important

• This package targets the mcp SDK FastMCP import path:
  • from mcp.server.fastmcp import FastMCP
• If you are using standalone fastmcp, this package will still usually work due to API overlap.

Publishing

Publishing is automated from GitHub Releases via GitHub Actions.

Initial repository setup still requires:

• configuring PyPI Trusted Publishing for this repository
• optionally protecting the pypi GitHub environment