Enterprise MCP Server

Production-grade FastMCP 3.x server template built for teams that need to scale: semantic tool retrieval, dynamic providers, parameterised resource templates, paginated tool lists, session-scoped role unlocking, middleware, and full auth.

---

Architecture

server.py               ← entry point — assembles everything
config/settings.py      ← ALL configuration  ← EDIT THIS FIRST
│
├── providers/          FastMCP 3.0 Dynamic Providers
│   └── registry.py     FileSystemProvider · OpenAPIProvider · ProxyProvider
│
├── transforms/         FastMCP 3.0 Transforms (middleware for providers)
│   └── pipeline.py     PrefixTransform · VersionFilter · TagFilter
│
├── tools/
│   ├── meta_tools.py   search_tools (Search Transform) · unlock_role (progressive disclosure)
│   └── example_tools.py  ← template for your own tools; drop files here
│
├── resources/
│   └── templates.py    Parameterised URIs: enterprise://tables/{name}/schema
│
├── middleware/
│   └── stack.py        Logging · RateLimiting · ResponseLimiting · Caching
│
├── auth/
│   └── setup.py        JWT · OAuth 2.1 · Bearer
│
└── utils/
    ├── lifespan.py     Startup / shutdown hooks
    └── otel.py         OpenTelemetry tracing

---

FastMCP 3.x Scale Features Used

Feature	Where	Config key
Pagination (list_page_size)	server.py	LIST_PAGE_SIZE
Dynamic Providers	providers/registry.py	PROVIDERS
Search Transforms (meta-tool)	tools/meta_tools.py	SEMANTIC_SEARCH
Resource Templates	resources/templates.py	RESOURCE_TEMPLATES
Session State + progressive disclosure	tools/meta_tools.py	ROLE_GATES
Component Versioning	tools/example_tools.py	VERSIONING
Tag-based visibility	transforms/pipeline.py	ROLE_GATES
Background Tasks	tools/example_tools.py	BACKGROUND_TASKS
Returnable errors	tools/example_tools.py	—
OpenTelemetry	utils/otel.py	OTEL

---

Quickstart

# 1. Install
pip install fastmcp>=3.4.1 httpx

# 2. Configure
#    Open config/settings.py and fill every  <CONFIGURE>  marker.

# 3. Run (development — hot reload)
fastmcp dev server.py

# 4. Run (production)
python server.py

Optional extras

pip install fastmcp[tasks]   # background tasks via Docket
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http  # OTEL

---

How to Add Your Own Tools

Drop a .py file into tools/ with a local mcp = FastMCP(...) instance and decorate your functions. FileSystemProvider picks them up automatically (set PROVIDERS.filesystem.reload = True for zero-restart hot-reload).

# tools/my_api_tools.py
from fastmcp import FastMCP, Context

mcp = FastMCP("my-api")

@mcp.tool(tags={"data", "read"}, version="1.0")
async def get_report(report_id: str, ctx: Context) -> dict:
    """Fetch an enterprise report by ID."""
    # ... your implementation
    return {}

Sensitive tools? Add tags={"admin"} (or any key in ROLE_GATES) and they are hidden from the default tool list. Clients call unlock_role("admin") after authenticating to reveal them for their session.

---

Semantic Search Flow

LLM calls search_tools(query="show me revenue by region")
         │
         ▼
   Your retrieval API  (SEMANTIC_SEARCH.api_base_url)
         │
         ▼
   Top-K tools above score_threshold returned to LLM
         │
         ▼
   LLM calls the specific tool it needs

The LLM never receives the full tool catalog — only the relevant subset.

---

Pagination Flow

Client sends  tools/list  (no cursor)
         │
         ▼
   Server returns  page 1  (LIST_PAGE_SIZE items) + nextCursor
         │
         ▼
   Client sends  tools/list?cursor=<nextCursor>
         │
         ▼
   ... repeat until nextCursor is null

fastmcp.Client.list_tools() handles this automatically. Use list_tools_mcp(cursor=...) for manual control.

---

Testing

pip install pytest pytest-asyncio
pytest tests/