Note App — FastAPI + MCP Demo

A simple JWT-authenticated note-taking API built with FastAPI, backed by SQLite via SQLAlchemy, and exposed as MCP tools for agents using fastapi-mcp.

Requirements

• Python 3.13+
• Node.js (only needed to run the MCP Inspector via npx)

Setup

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Create a .env file in the project root (see src/environment.py for the full list of settings):

USERNAME=admin
PASSWORD=changeme
JWT_SECRET=some-long-random-secret
JWT_EXPIRATION_MINUTES=60   # optional, defaults to 60

Running the server

python server.py

This starts uvicorn on http://0.0.0.0:8000, serving src.app:app.

• Swagger UI: http://localhost:8000/docs
• The root URL / redirects to /docs

Authentication

Get an access token:

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "changeme"}'

Use the returned access_token as a Bearer token on all /notes endpoints:

curl http://localhost:8000/notes/ \
  -H "Authorization: Bearer <access_token>"

Notes API

Method	Path	Description
GET	/notes/	List notes
GET	/notes/{id}	Get a note
POST	/notes/	Create a note
PUT	/notes/{id}	Update a note
DELETE	/notes/{id}	Delete a note

Using the MCP server

The app mounts an MCP server at /mcp, exposing every endpoint tagged Note as an MCP tool. Requests require the same Bearer token as the REST API, forwarded via the authorization header.

Inspecting it with MCP Inspector

1. Start the server: python server.py
2. In a separate terminal, launch the inspector:

   npx @modelcontextprotocol/inspector
   

3. In the inspector UI, set:
   • Transport: Streamable HTTP
   • URL: http://127.0.0.1:8000/mcp
   • Header: Authorization: Bearer <access_token> (obtained from /auth/login)
4. Click Connect, go to the Tools tab, and click List Tools to see list_notes, get_note, create_note, update_note, delete_note.
5. Select a tool, fill in parameters, and click Run Tool to test it.

Connecting from an MCP client (e.g. Claude Desktop)

Since the server requires auth headers, use mcp-remote as a bridge:

{
  "mcpServers": {
    "note-app": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <access_token>"
      }
    }
  }
}

Project structure

server.py                  # entrypoint (uvicorn runner)
src/
  app.py                   # FastAPI app + MCP mount
  environment.py           # settings loaded from .env
  modules/
    auth/                  # login route, JWT issuing/verification
    note/                  # notes CRUD (model, schema, service, route)
  sqlalchemy/              # base model + engine/session setup

Dev tooling

Config files are included for:

ruff check .   # linting (ruff.toml)
mypy .         # type checking (mypy.ini)