Skip to content

README.md

Latest commit

 

History

History
207 lines (157 loc) · 6.32 KB

README.md

File metadata and controls

207 lines (157 loc) · 6.32 KB

MCP Server Creation - Notes App

A full-stack application that demonstrates how to create a Model Context Protocol (MCP) server with authentication, a React frontend, and a Python backend with SQLite database.

https://www.loom.com/share/12b6eeecdc404862a03cf5c804315aaa?sid=d9a7c09c-4356-4092-8fc8-3a1b6123e071

🏗️ Project Architecture

This project consists of three main components:

  • Backend: Python FastMCP server with SQLite database
  • Frontend: React application with Stytch authentication
  • External Services: Stytch for authentication, ngrok for tunneling

🚀 Quick Start

Prerequisites

  • Python 3.13+
  • Node.js 18+
  • ngrok CLI tool
  • Stytch account and project

Backend Setup

cd backend
uv sync  # Install Python dependencies
uv run python main.py

Frontend Setup

cd frontend
npm install
npm run dev

Start ngrok Tunnel

ngrok http 8000

🔧 Backend (Python FastMCP Server)

The backend is built using FastMCP, a framework for creating MCP servers with built-in authentication support.

Key Features

  • FastMCP Server: Implements the Model Context Protocol
  • SQLite Database: Stores user notes with SQLAlchemy ORM
  • JWT Authentication: Uses Stytch for secure user authentication
  • CORS Support: Configured for cross-origin requests

Database Schema

class Note(Base):
    __tablename__ = 'notes'
    id = Column(Integer, primary_key=True, index=True)
    user_id = Column(String, index=True, nullable=False)
    title = Column(String, nullable=False)
    content = Column(Text, nullable=False)

MCP Tools Available

  • get_my_notes(): Retrieve all notes for the authenticated user
  • add_note(title, content): Create a new note
  • delete_note(note_id): Remove a note by ID

Dependencies

  • fastmcp>=2.10.6: MCP server framework
  • sqlalchemy>=2.0.42: Database ORM
  • stytch>=13.12.0: Authentication service
  • dotenv>=0.9.9: Environment variable management
  • python-jose>=3.5.0: Jwt token unloading

🎨 Frontend (React + Stytch)

The frontend is a React application built with Vite that provides a user interface for authentication and note management.

Key Features

  • Stytch Authentication: password-based login
  • Responsive Design: Centered layout with modern styling
  • Protected Routes: Authentication-based access control

Authentication Providers

  • Password-based authentication
  • Note: need to set redirect urls with Stytch if using Magic link or Oauth authentication

Dependencies

  • @stytch/react: Stytch React SDK
  • react: React framework
  • vite: Build tool and dev server

🔐 External Services Setup

Stytch Authentication

  1. Create Stytch Project

    • Sign up at stytch.com
    • Create a new project
    • Note your Project ID, Secret and Domain

  2. Configure Frontend SDK

    • Go to Frontend SDK in Stytch dashboard
    • Enable SDK in test mode
    • Add authorized domains (e.g., http://localhost:5173 for development)

  3. Environment Variables Create a .env file in the backend directory:

    STYTCH_DOMAIN=https://your-project.stytch.com
STYTCH_PROJECT_ID=your-project-id

  4. OAuth Configuration

    • Configure OAuth providers (Google, Facebook)
    • Set redirect URLs for login/signup
    • Enable dynamic client registration

ngrok Tunneling

ngrok creates a secure tunnel to your local server, making it accessible from the internet.

  1. Install ngrok

    # macOS
brew install ngrok

# Or download from https://ngrok.com/

  2. Start Tunnel

    ngrok http 8000

  3. Use Tunnel URL

    • Copy the HTTPS URL provided by ngrok
    • Add /mcp to the URL when configuring Claude
    • Example: https://abc123.ngrok-free.app/mcp

🤖 Claude MCP Integration

To connect Claude to your MCP server:

  1. Start Backend: uv run python main.py
  2. Start ngrok: ngrok http 8000
  3. Add MCP Server in Claude: 
    claude mcp add --transport http --url https://your-ngrok-url.ngrok-free.app/mcp
  4. Authentication with Claude: 'claude' then run /mcp to authenticate

📁 Project Structure

MCP_Server_Creation/
├── backend/
│   ├── main.py              # FastMCP server entry point
│   ├── database.py          # Database models and repository
│   ├── pyproject.toml       # Python dependencies
│   └── notes.db            # SQLite database file
├── frontend/
│   ├── src/
│   │   ├── App.jsx         # Main React component
│   │   └── main.jsx        # React entry point
│   ├── package.json        # Node.js dependencies
│   └── vite.config.js      # Vite configuration
└── README.md               # This file

🔄 Development Workflow

  1. Backend Development

    • Make changes to main.py or database.py
    • Restart the server: uv run python main.py

  2. Frontend Development

    • Make changes to React components
    • Vite will hot-reload automatically

  3. Testing MCP Integration

    • Ensure backend is running
    • Ensure ngrok tunnel is active
    • Test MCP tools through Claude

🚨 Important Notes

  • Localhost Limitation: Claude Code doesn't support localhost MCP servers, ngrok can help redirect an external uri to a local port
  • ngrok Required: Always use ngrok for external access during development
  • Stytch Configuration: Ensure authorized domains match your development URLs
  • Environment Variables: Keep .env file secure and either never commit to version control OR remove secrets before committing

🆘 Troubleshooting

Common Issues

  1. Import Errors: Ensure all dependencies are installed with uv sync
  2. Authentication Failures: Check Stytch project configuration and environment variables
  3. CORS Errors: Verify CORS middleware configuration in backend
  4. ngrok Connection Issues: Ensure backend is running on port 8000 before starting ngrok

Getting Help