FastMCP Feedback

Production-ready feedback collection system for FastMCP servers.

Add structured feedback collection (bug reports, feature requests, general feedback) to any FastMCP server with a single line of code.

Features

• One-Line Integration - Add feedback tools to any FastMCP server instantly
• Modular Mixins - Selective tool registration for fine-grained control
• Multi-Database Support - SQLite (dev), PostgreSQL, MySQL (production)
• Privacy-Compliant Analytics - Optional usage insights without sensitive data
• Type-Safe - Full Pydantic validation and type hints
• Well-Tested - 97%+ test coverage

Installation

From PyPI (Recommended)

# Using uv (recommended)
uv add fastmcp-feedback

# Using pip
pip install fastmcp-feedback

# With PostgreSQL support
uv add "fastmcp-feedback[postgresql]"

From Git (Latest Development)

# Latest from main branch
uv add git+https://git.supported.systems/fastmcp-feedback/fastmcp-feedback.git

# Specific release tag
uv add git+https://git.supported.systems/fastmcp-feedback/fastmcp-feedback.git@2026.01.12

# Specific branch (for testing PRs)
uv add git+https://git.supported.systems/fastmcp-feedback/fastmcp-feedback.git@feature-branch

Local Development Install

For contributors or local modifications:

# Clone the repository
git clone git@git.supported.systems:fastmcp-feedback/fastmcp-feedback.git
cd fastmcp-feedback

# Create virtual environment and install in editable mode
uv venv
uv pip install -e ".[dev]"

# Run tests to verify
uv run pytest

Quick Start

Basic Integration (One Line)

from fastmcp import FastMCP
from fastmcp_feedback import add_feedback_tools

app = FastMCP("My Server")
add_feedback_tools(app, database_url="sqlite:///feedback.db")

# Your server now has five tools:
# - submit_feedback: bug reports, feature requests, improvements, questions
# - list_feedback: page through feedback, filtered by type or status
# - get_feedback_statistics: counts by type and status, plus the last 7 days
# - update_feedback_status: move an item through open -> in_progress -> resolved -> closed
# - delete_feedback: remove an item

Pass a database_url. Without one the tools use an in-memory SQLite database, which is handy for tests but loses everything when the process exits.

PostgreSQL

add_feedback_tools(app, database_url="postgresql://user:pass@db.example.com/feedback")

Install the driver with uv add "fastmcp-feedback[postgresql]".

Prefixed Tool Names

add_feedback_tools(app, database_url="sqlite:///feedback.db", prefix="support")
# support_submit_feedback, support_list_feedback, ...

The prefix and tool name are joined with separator (default _), so leave the trailing underscore off the prefix.

Usage Analytics

from fastmcp_feedback import FeedbackInsights

add_feedback_tools(
    app,
    database_url="sqlite:///feedback.db",
    insights=FeedbackInsights(enabled=True),
)

Analytics are off unless you pass FeedbackInsights(enabled=True) or set FEEDBACK_INSIGHTS_ENABLED=true. When enabled they record tool usage and submission metadata (type, lengths, timing), never feedback text or contact details.

Advanced Usage

Mixin Architecture

Pick only the tool groups you want to expose:

from fastmcp_feedback import (
    ManagementMixin,
    RetrievalMixin,
    SubmissionMixin,
    get_database_session,
)

db = get_database_session("sqlite:///feedback.db")

# Public server: submission only
SubmissionMixin(db).register_tools(app)

# Reporting tools under a prefix: analytics_list_feedback, ...
RetrievalMixin(db).register_tools(app, prefix="analytics")

# Admin server gets the workflow tools
ManagementMixin(db).register_tools(admin_app, prefix="admin")

Available Mixins

Multi-Tenant Pattern

# Each tenant gets its own database
def add_tenant_tools(tenant_id: str):
    db = get_database_session(f"sqlite:///data/{tenant_id}.db")
    SubmissionMixin(db).register_tools(app, prefix=f"tenant_{tenant_id}")

Server Composition

from fastmcp_feedback import create_feedback_server

feedback_server = create_feedback_server(
    "Feedback API", database_url="sqlite:///feedback.db"
)

# Tools appear on main_app as feedback_submit_feedback, feedback_list_feedback, ...
main_app.mount(feedback_server, "feedback")

mount() works on every supported FastMCP version. import_server() was removed in FastMCP 4.

Compatibility

Tested against FastMCP 2.12, 2.14 and 4.0 on every commit. The dependency is declared as fastmcp>=2.12.2,<5, and the ceiling moves up once a new major version passes the suite.

API Reference

add_feedback_tools(mcp, database_url=None, insights=None, prefix="", separator="_")

Add all five feedback tools to a FastMCP server.

Parameters:

• mcp: FastMCP server instance
• database_url: SQLAlchemy URL. Defaults to in-memory SQLite (sqlite:///:memory:)
• insights: a FeedbackInsights instance. Defaults to one with analytics disabled
• prefix: prepended to every tool name
• separator: placed between prefix and the tool name

Feedback Types

• bug - something is broken
• feature - a new capability
• improvement - make an existing capability better
• question - unclear behavior or usage

Status Workflow

open → in_progress → resolved → closed

Documentation

Full documentation: https://fastmcp-feedback.l.supported.systems

• Quick Start Tutorial
• Architecture
• API Reference
• Integration Patterns

Examples

See the fastmcp-feedback-showcase repository for comprehensive examples demonstrating all capabilities:

uvx fastmcp-feedback-showcase  # Run full demo

Contributing

We welcome contributions! FastMCP Feedback is designed to be contributor-friendly.

Quick Contribution Setup

# Fork and clone
git clone git@git.supported.systems:YOUR_USERNAME/fastmcp-feedback.git
cd fastmcp-feedback

# Install with dev dependencies
uv venv
uv pip install -e ".[dev]"

# Create feature branch
git checkout -b feature/your-feature

# Make changes, run tests
uv run pytest
uv run ruff check .

# Submit PR

See CONTRIBUTING.md for detailed guidelines.

Versioning

This project uses calendar versioning (CalVer): YYYY.MM.DD

• 2026.01.12 = Release on January 12, 2026
• Multiple releases on same day: 2026.01.12.1, 2026.01.12.2

This makes it clear when each release was made and simplifies dependency management.

License

MIT License - see LICENSE for details.

Links

• Documentation: https://fastmcp-feedback.l.supported.systems
• Repository: https://git.supported.systems/fastmcp-feedback/fastmcp-feedback
• Issues: https://git.supported.systems/fastmcp-feedback/fastmcp-feedback/issues
• Showcase: https://git.supported.systems/fastmcp-feedback/fastmcp-example
• FastMCP: https://gofastmcp.com