fastmcp-server

Production-ready FastMCP server image with dynamic loading of tools, resources, prompts, and knowledge bases from multiple sources.

Run your own MCP server anywhere — Docker, Compose, Swarm, Kubernetes, or any container runtime. Define tools in Python, mount them, and your server is live.

Quick Start

# Create a tool
mkdir -p tools
cat > tools/hello.py << 'EOF'
def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"
EOF

# Run the server
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/tools:/app/inline/tools \
  docker.io/helmforge/fastmcp-server:0.4.0

Your MCP server is now available at http://localhost:8000/mcp. The built-in Web UI is at http://localhost:8000/ui.

How It Works

The server loads MCP components (tools, resources, prompts, knowledge) from a workspace directory. On startup, it syncs files from one or more sources into the workspace, registers everything with FastMCP, and exposes the server over HTTP.

Sources (Inline, S3, Git)
        │
        ▼
  /app/workspace/
  ├── tools/*.py         → registered as MCP tools
  ├── resources/*.py     → registered as MCP resources
  ├── prompts/*.py       → registered as MCP prompts
  └── knowledge/*        → served as knowledge:// resources
        │
        ▼
  FastMCP Server (:8000/mcp)
  ├── /ui               → Web dashboard
  ├── /healthz          → Liveness probe
  ├── /readyz           → Readiness probe
  ├── /startupz         → Startup probe
  ├── /debug/info       → Server diagnostics
  ├── /metrics          → Prometheus metrics (opt-in)
  └── /api/*            → JSON API for UI

Sources

The image supports three data sources with merge precedence (highest first):

Source	Best For	Limit
Inline (volume mount at `/app/inline/`)	Quick setup, small configs	Host filesystem
S3 (AWS S3, MinIO, Cloudflare R2)	Teams, CI/CD pipelines, large knowledge bases	Unlimited
Git (any HTTPS repo)	Version-controlled tools, collaboration	Repo size

All sources can be combined. Inline always wins on conflicts.

Running with Docker Compose

services:
  mcp-server:
    image: docker.io/helmforge/fastmcp-server:0.4.0
    ports:
      - "8000:8000"
    volumes:
      - ./tools:/app/inline/tools
      - ./resources:/app/inline/resources
      - ./prompts:/app/inline/prompts
      - ./knowledge:/app/inline/knowledge
    environment:
      MCP_SERVER_NAME: my-mcp-server
      MCP_AUTH_TYPE: bearer
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8000/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

Running with S3 (MinIO example)

services:
  mcp-server:
    image: docker.io/helmforge/fastmcp-server:0.4.0
    ports:
      - "8000:8000"
    environment:
      SOURCE_S3_ENABLED: "true"
      SOURCE_S3_ENDPOINT: http://minio:9000
      SOURCE_S3_BUCKET: mcp-tools
      SOURCE_S3_ACCESS_KEY: minioadmin
      SOURCE_S3_SECRET_KEY: minioadmin

  minio:
    image: docker.io/minio/minio:RELEASE.2025-04-03T14-56-28Z
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin

Running with Git Source

docker run -d \
  -p 8000:8000 \
  -e SOURCE_GIT_ENABLED=true \
  -e SOURCE_GIT_REPOSITORY=https://github.com/myorg/mcp-tools.git \
  -e SOURCE_GIT_BRANCH=main \
  docker.io/helmforge/fastmcp-server:0.4.0

For private repos, set SOURCE_GIT_TOKEN with a personal access token.

Writing Tools

Create a .py file in tools/. By default, every public function defined in that module becomes an MCP tool:

def get_weather(city: str) -> str:
    """Get current weather for a city."""
    import httpx
    return httpx.get(f"https://wttr.in/{city}?format=3").text

def roll_dice(sides: int = 6) -> int:
    """Roll a die with the given number of sides."""
    import random
    return random.randint(1, sides)

Utility modules are supported too. Files named like *_helpers.py are skipped by default. For any other utility module, keep helpers private (_helper) or disable auto-registration explicitly:

__mcp_auto_register__ = False

def evidence_true(data, *keys):
    return True

If you want exact control over exports, declare a TOOLS allowlist:

TOOLS = ["deploy"]

def deploy(service: str, version: str) -> str:
    """Deploy a service."""
    return f"Deployed {service}@{version}"

def helper() -> str:
    return "not registered"

Tool Metadata

Add optional module-level variables to control tool registration:

__tags__ = {"devops", "production"}        # Categorization tags
__timeout__ = 30.0                          # Execution timeout (seconds)
__annotations_mcp__ = {                     # MCP behavior hints
    "destructiveHint": True,
    "title": "Deploy Service"
}

def deploy(service: str, version: str) -> str:
    """Deploy a service to production."""
    return f"Deployed {service}@{version}"

Async Tools

Both async def and def functions work. Async is preferred for I/O-bound operations:

async def fetch_url(url: str) -> str:
    """Fetch content from a URL."""
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text

Structured Output

Return ToolResult for full control over response format:

from fastmcp.tools.tool import ToolResult

def analyze(data: str) -> ToolResult:
    """Analyze data with structured output."""
    return ToolResult(
        content="Analysis complete",
        structured_content={"word_count": len(data.split())},
        meta={"version": "1.0"}
    )

Writing Resources

Create a .py file in resources/ with a RESOURCE_URI constant and a handler function:

import json

RESOURCE_URI = "config://app"

def get_config() -> str:
    """Application configuration."""
    return json.dumps({"version": "1.0", "env": "production"}, indent=2)

Important: Resource handlers must return str, bytes, or list[ResourceContent]. Returning a dict directly will cause a serialization error.

Resource Templates

Use {param} placeholders in URIs for parameterized resources:

import json

RESOURCE_URI = "users://{user_id}/profile"

def get_profile(user_id: str) -> str:
    """Get user profile by ID."""
    return json.dumps({"user_id": user_id, "name": f"User {user_id}"}, indent=2)

Multiple Resources per File

Use a RESOURCES dict to register multiple resources from one file:

import json

RESOURCES = {
    "status://health": "get_health",
    "status://version": "get_version",
}

def get_health() -> str:
    return json.dumps({"status": "ok"}, indent=2)

def get_version() -> str:
    return "1.0.0"

Writing Prompts

Create a .py file in prompts/. Every public function becomes an MCP prompt:

def summarize(text: str) -> str:
    """Summarize the provided text."""
    return f"Please provide a concise summary of:\n\n{text}"

Knowledge Base

Any file placed in knowledge/ is served as a knowledge:// resource. Supports text, markdown, JSON, YAML, or any UTF-8 file.

knowledge/
├── product-overview.md
├── api-reference.json
└── troubleshooting/
    ├── common-errors.md
    └── faq.md

These become accessible as knowledge://product-overview.md, knowledge://troubleshooting/common-errors.md, etc.

Authentication

Type	Variables	Use Case
None	`MCP_AUTH_TYPE=none`	Development, internal networks
Bearer	`MCP_AUTH_TYPE=bearer` + `MCP_AUTH_TOKEN`	API keys, service accounts
JWT	`MCP_AUTH_TYPE=jwt` + `MCP_AUTH_JWT_*`	OAuth/OIDC, enterprise SSO

Web UI

The embedded dashboard at /ui provides:

Dashboard — Server name, version, uptime, component counts, source status
Tools Explorer — All registered tools with descriptions, parameters, tags, timeout
Resources Explorer — Resources and templates with URIs, MIME types
Prompts Explorer — All prompts with descriptions

Auto-refreshes every 15 seconds. Disable with MCP_UI_ENABLED=false.

Observability

Health Endpoints

Endpoint	Purpose	When 200
`GET /healthz`	Liveness	Always (process is running)
`GET /readyz`	Readiness	Sources synced + components loaded
`GET /startupz`	Startup	Full initialization complete

Diagnostics

GET /debug/info returns full server diagnostics: version, FastMCP version, uptime, component details, source status, auth type, and configuration.

Prometheus Metrics

Enable with MCP_METRICS_ENABLED=true. Exposes at /metrics:

mcp_tools_total — Number of registered tools
mcp_resources_total — Number of registered resources
mcp_prompts_total — Number of registered prompts
mcp_knowledge_total — Number of knowledge files
mcp_tool_calls_total{tool} — Tool invocation counter
mcp_tool_duration_seconds{tool} — Tool execution duration histogram
mcp_tool_errors_total{tool} — Tool error counter
mcp_sources_sync_total{source,status} — Source sync operations
mcp_auth_requests_total{result} — Auth attempt counter

Structured Logging

Set LOG_FORMAT=json for JSON-structured logs compatible with Loki, ELK, CloudWatch, and Datadog:

{
  "timestamp": "2026-04-05T10:30:00+00:00",
  "level": "INFO",
  "logger": "fastmcp-server.builder",
  "message": "Registered tool: greet"
}

Environment Variables

Server

Variable	Default	Description
`MCP_SERVER_NAME`	`fastmcp-server`	Server display name
`MCP_HOST`	`0.0.0.0`	Listen address
`MCP_PORT`	`8000`	Listen port
`MCP_PATH`	`/mcp`	HTTP endpoint path
`MCP_WORKSPACE`	`/app/workspace`	Workspace directory
`LOG_LEVEL`	`INFO`	Logging level
`LOG_FORMAT`	`text`	Log format: `text` or `json`
`MCP_MASK_ERROR_DETAILS`	`false`	Hide internal error details from clients
`MCP_ON_DUPLICATE_TOOLS`	`warn`	Duplicate handling: `warn`, `error`, `replace`, `ignore`
`MCP_STRICT_LOADING`	`false`	Fail on boot if any tool/resource has errors
`MCP_UI_ENABLED`	`true`	Enable built-in Web UI at `/ui`
`MCP_METRICS_ENABLED`	`false`	Enable Prometheus metrics at `/metrics`
`EXTRA_PIP_PACKAGES`		Comma-separated pip packages to install at startup

Authentication

Variable	Default	Description
`MCP_AUTH_TYPE`	`none`	`bearer`, `jwt`, or `none`
`MCP_AUTH_TOKEN`		Bearer token value
`MCP_AUTH_JWT_ISSUER`		JWT issuer
`MCP_AUTH_JWT_AUDIENCE`		JWT audience
`MCP_AUTH_JWT_JWKS_URI`		JWKS endpoint URL

S3 Source

Variable	Default	Description
`SOURCE_S3_ENABLED`	`false`	Enable S3 sync
`SOURCE_S3_ENDPOINT`		S3-compatible endpoint URL
`SOURCE_S3_BUCKET`		Bucket name
`SOURCE_S3_REGION`	`us-east-1`	AWS region
`SOURCE_S3_PREFIX`		Key prefix filter
`SOURCE_S3_ACCESS_KEY`		Access key ID
`SOURCE_S3_SECRET_KEY`		Secret access key

Git Source

Variable	Default	Description
`SOURCE_GIT_ENABLED`	`false`	Enable Git sync
`SOURCE_GIT_REPOSITORY`		Repository HTTPS URL
`SOURCE_GIT_BRANCH`	`main`	Branch to clone
`SOURCE_GIT_PATH`		Subdirectory within the repo
`SOURCE_GIT_TOKEN`		Auth token for private repos

Init Container Pattern

For Kubernetes, separate source syncing from server startup using sync_only.py:

python /app/sync_only.py

This script runs sync_sources() and exits. Use it as a Kubernetes init container to pre-populate the workspace volume before the main server starts.

Deployment Options

Method	Docs
Docker / Docker Compose / Swarm	This README
Kubernetes (Helm)	helmforge/charts — fastmcp-server

Connecting MCP Clients

Once your FastMCP server is running and accessible, connect AI assistants to it as an MCP server.

Claude Code

Add the server to your Claude Code settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

With bearer authentication:

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Codex (VS Code Extension)

Add to your Codex configuration file (~/.codex/config.toml):

[mcp_servers.my-mcp-server]
enabled = true
url = "https://mcp.example.com/mcp"

[mcp_servers.my-mcp-server.http_headers]
Authorization = "Bearer <your-token>"

Without authentication (development):

[mcp_servers.my-mcp-server]
enabled = true
url = "https://mcp.example.com/mcp"

Local Development

When running locally with Docker, use http://localhost:8000/mcp as the URL and omit authentication headers if MCP_AUTH_TYPE=none.

License

Apache-2.0 — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github/workflows		.github/workflows
examples		examples
src		src
tests		tests
validation		validation
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

fastmcp-server

Quick Start

How It Works

Sources

Running with Docker Compose

Running with S3 (MinIO example)

Running with Git Source

Writing Tools

Tool Metadata

Async Tools

Structured Output

Writing Resources

Resource Templates

Multiple Resources per File

Writing Prompts

Knowledge Base

Authentication

Web UI

Observability

Health Endpoints

Diagnostics

Prometheus Metrics

Structured Logging

Environment Variables

Server

Authentication

S3 Source

Git Source

Init Container Pattern

Deployment Options

Connecting MCP Clients

Claude Code

Codex (VS Code Extension)

Local Development

License

About

Topics

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 26

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages