MCP App with Authentication

This project implements a secure, database-backed OAuth 2.1 authorization server and MCP App on top of FastMCP. It allows clients like Claude, ChatGPT, or the MCP Inspector to sign in using Google OAuth, execute authorized tools, and display details in an MCP App UI.

---

Setup & Running Guide

1. Ngrok Setup & Static URL Configuration

1. Install Ngrok: Follow the setup and installation instructions on the official ngrok Setup & Installation page.

2. Configure your Static Domain: To keep your public OAuth redirect URL persistent and avoid updating the Google Cloud Console settings every time you restart ngrok, configure a static development domain in your local ngrok.yml file:

   Run the ngrok configuration editor:

   ngrok config edit
   

3. Add Endpoint Configuration: Paste the following configuration structure into the editor, replacing authtoken with your actual token from the ngrok dashboard:

   version: 3
   agent:
     authtoken: YOUR_NGROK_AUTHTOKEN
   
   endpoints:
     - name: local
       url: <your-static-domain>.ngrok-free.app
       upstream:
         url: 8000
   

4. Save and close the editor.

5. Launch the static tunnel:

   ngrok start local
   

Keep this tunnel active. Your public URL will always be https://<your-static-domain>.ngrok-free.app.

---

2. Google Cloud Console Setup

1. Create a Google Cloud Project: Go to the Google Cloud Console and create a new project.
2. Configure OAuth Consent Screen:
   • Go to APIs & Services > OAuth consent screen.
   • Choose External user type and fill out the required app information.
   • Add scopes: .../auth/userinfo.email, .../auth/userinfo.profile, and openid.
   • Add your Google account as a test user.
3. Create Credentials:
   • Go to APIs & Services > Credentials.
   • Click Create Credentials > OAuth client ID.
   • Choose Web application as the application type.
   • Under Authorized JavaScript origins, add:
     • https://<your-static-domain>.ngrok-free.app
   • Under Authorized redirect URIs, add:
     • https://<your-static-domain>.ngrok-free.app/auth/google/callback (Our server callback)
4. Copy Secrets:
   • Save the client ID and client secret. These will be assigned to the environment variables GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET at server launch.

---

3. Start the MCP Server

Create a .env file in the root of the project to store your configurations and Google credentials securely:

PUBLIC_URL="https://<your-static-domain>.ngrok-free.app"
GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

Once your .env file is set up, start the server:

uv run python main.py

---

4. Build the Vite UI (React + Tailwind CSS)

To compile the React + Tailwind single-file HTML bundle to ui/dist/index.html:

cd ui
bun run build

---

5. Start the MCP Inspector

Run the local MCP Inspector using Bun (bunx) or NPM (npx):

# Using Bun (bunx)
bunx @modelcontextprotocol/inspector --transport http --server-url https://<your-static-domain>.ngrok-free.app/mcp

# Or using NPM (npx)
npx @modelcontextprotocol/inspector --transport http --server-url https://<your-static-domain>.ngrok-free.app/mcp

Open the generated local URL, click Connect, and complete the Google login flow to launch the MCP App UI.

---

References

• MCP Apps Overview
• Build an MCP App
• Understanding Authorization in MCP