MCP Mock Store Example
This repository contains an end-to-end example of a fastMCP server that exposes a mock e-commerce store backed by a FastAPI application and a PostgreSQL database. It demonstrates how to share the same data source between a REST API and Model Context Protocol (MCP) tools so that conversational AI agents can explore store information such as customers, inventory, and orders.
Project layout
.
├── app/ # FastAPI application (SQLAlchemy models, schemas, CRUD helpers)
├── mcp_server/ # fastMCP server exposing store data as tools
├── sql/ # SQL scripts for schema and seed data
├── docker-compose.yml # Local PostgreSQL instance with preloaded data
├── requirements.txt # Python dependencies for both servers
└── .env.example # Example environment variables
Prerequisites
- Python 3.11+
- Docker and Docker Compose (v2 or newer)
pipfor installing Python dependencies
1. Start the database
docker compose up -d
The PostgreSQL container mounts the sql/ directory into /docker-entrypoint-initdb.d, so the schema (create_tables.sql) and sample data (seed_data.sql) are loaded automatically the first time the container starts.
2. Configure environment variables
Copy the example environment file and adjust it if you changed any credentials or hostnames:
cp .env.example .env
Both the FastAPI service and the fastMCP server read the DATABASE_URL environment variable. The default connection string assumes you are running locally with the docker-compose.yml configuration.
3. Install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
4. Run the FastAPI backend
uvicorn app.main:app --reload
Example endpoints
GET /customers– list all customersGET /customers/{id}– retrieve a single customerGET /products– browse available productsGET /inventory– inspect inventory levelsGET /orders– view orders including nested line itemsGET /orders/{id}– fetch a specific order
5. Run the fastMCP server
python -m mcp_server
The server registers the following tools:
| Tool name | Description |
|---|---|
list_customers | Returns all customers and their metadata. |
list_products | Lists available products. |
list_inventory | Provides current inventory levels. |
list_orders | Retrieves orders with customer and line item data. |
get_order | Returns a single order by ID, or an error if missing. |
get_store_summary | Aggregates counts and high-level metrics. |
Each tool responds with JSON derived from the same SQLAlchemy models used by the FastAPI backend, ensuring consistent representations across HTTP and MCP interfaces.
6. Connect from popular AI chatbots
Below are quick-start notes for common MCP-compatible clients. Substitute the path to your virtual environment's Python interpreter if different (e.g., .venv/bin/python).
Anthropic Claude Desktop
- Open Claude Desktop and navigate to Settings → Configure MCP Servers.
- Add a new server with:
- Command:
python - Arguments:
-m mcp_server - Working directory: the root of this repository.
- Command:
- Ensure the
DATABASE_URLenvironment variable is available to Claude (e.g., by launching Claude from a shell session where it is exported). - Claude can now call tools such as
get_store_summaryduring conversations.
Cursor IDE
- Open Cursor and run the command Cursor: Configure MCP Servers.
- Create an entry with the command
pythonand arguments-m mcp_server. - Optionally specify environment variables via the configuration panel so the MCP server can reach the PostgreSQL instance.
- Use the “Connect MCP Server” command to make tools available in the chat sidebar.
VS Code + Continue
-
Install the Continue extension (version 0.9.0+).
-
Open the Continue settings (
continue.json) and add:{ "servers": [ { "name": "mock-store", "command": "python", "args": ["-m", "mcp_server"], "cwd": "${workspaceFolder}", "env": { "DATABASE_URL": "postgresql+psycopg2://mcp_user:mcp_password@localhost:5432/mcp_store" } } ] } -
Restart Continue; the mock store tools will appear in the MCP tool palette.
OpenAI Desktop / ChatGPT Desktop (beta MCP support)
- Launch the client from a terminal with the virtual environment activated so the MCP server dependencies are available.
- In the MCP configuration UI, add a custom server pointing to
python -m mcp_server. - Use the UI to map environment variables or rely on your shell environment.
Tip: If a client requires an absolute path to the interpreter, run
which python(Linux/macOS) orwhere python(Windows) inside the virtual environment and paste that path into the MCP configuration.
Database management
-
Reset data: stop the containers (
docker compose down), delete the volume (docker volume rm mcp_postgres-data), and start again. -
Manual migrations: you can rerun the SQL scripts with
psql:psql postgresql://mcp_user:mcp_password@localhost:5432/mcp_store -f sql/create_tables.sql psql postgresql://mcp_user:mcp_password@localhost:5432/mcp_store -f sql/seed_data.sql
Testing the MCP tools manually
Once the server is running, you can issue direct requests with the fastmcp client utilities:
python -m fastmcp.client --command "get_store_summary"
Refer to the fastmcp documentation for more advanced usage such as streaming outputs or structured arguments.
License
This example is provided under the MIT license. Use it as a starting point for your own MCP-integrated services.