Auth MCP Server

A remote MCP (Model Context Protocol) server protected by Auth0 OAuth. It exposes tools for the authenticated user (greet, writing prompts) and optional Gmail access (list recent emails for the logged-in user).

Prerequisites

• Python 3.13+

• uv (install)

• Auth0 account (for MCP authentication)

• Google Cloud project (only if you want Gmail tools)

End-to-end setup

1. Clone and install

git clone <your-repo-url>
cd auth-mcp-remote
uv sync

2. Auth0 setup (required)

You need an Auth0 Application and API so MCP clients can authenticate.

1. Create an Auth0 account at auth0.com and open the Dashboard.

2. Create an API (this is your “audience”):

   • Applications → APIs → Create API

   • Name: e.g. Auth MCP Server

   • Identifier: e.g. https://your-server.example.com/mcp (use your real MCP URL; this is your Audience)

   • Signing Algorithm: RS256 → Create

3. Create an Application (for the MCP client):

   • Applications → Applications → Create Application

   • Name: e.g. MCP Client

   • Type: Machine to Machine (or Native for local clients)

   • Choose your API and authorize it; grant scopes: openid, profile, email

   • Note the Client ID and Client Secret if you need them for the client

4. Note your Auth0 domain (e.g. your-tenant.auth0.com) from the Auth0 Dashboard.

5. Environment variables (see step 5 below): you will set:

   • AUTH0_DOMAIN = your tenant domain (e.g. your-tenant.auth0.com)

   • AUTH0_AUDIENCE = the API Identifier you set (e.g. https://your-server.example.com/mcp)

   • RESOURCE_SERVER_URL = same as audience, or the public URL where your MCP server is reached (e.g. https://your-server.example.com/mcp)

3. Google Cloud setup (optional, for Gmail tools)

Only needed if you want list_my_recent_emails and link_my_gmail.

1. Create or select a project in Google Cloud Console.

2. Enable Gmail API:

   • APIs & Services → Library → search Gmail API → Enable.

3. Configure OAuth consent screen:

   • APIs & Services → OAuth consent screen.

   • User type: External → Create.

   • App information: name (e.g. dibya-mcp-gmail), support email, developer contact → Save and Continue.

   • Scopes → Add or Remove Scopes → add https://www.googleapis.com/auth/gmail.readonly → Save and Continue.

   • Test users (if in Testing mode): add the Gmail addresses that will use the app (e.g. your own) → Save and Continue.

   • Summary → Back to Dashboard.

4. Create OAuth 2.0 credentials:

   • APIs & Services → Credentials → Create Credentials → OAuth client ID.

   • Application type: Desktop app (or Web application with redirect URI below).

   • Name: e.g. MCP Gmail.

   • If Web application: under Authorized redirect URIs add exactly: http://localhost:8080/.

   • Create → copy Client ID and Client Secret.

5. Environment variables (see step 5): you will set:

   • GOOGLE_CLIENT_ID = OAuth client Client ID

   • GOOGLE_CLIENT_SECRET = OAuth client Client Secret

4. Get a Gmail refresh token (optional, for Gmail tools)

The MCP server needs a refresh token issued by your OAuth client (tokens from Google OAuth Playground will not work).

1. Add redirect URI in Google Cloud (if not already):

   • APIs & Services → Credentials → your OAuth 2.0 Client ID.

   • Under Authorized redirect URIs add: http://localhost:8080/ (with trailing slash) → Save.

2. Run the one-time script from the project root:

   uv run python scripts/get_gmail_refresh_token.py

   • The script prints the exact redirect URI to add if needed.

   • Press Enter to open the browser; sign in with the Google account whose Gmail you want to use.

   • After consent, the script prints a refresh token. Copy it.

3. Link Gmail in the MCP server (after the server is running and you are authenticated with Auth0):

   • Call the MCP tool link_my_gmail with that refresh token. The server stores it for your Auth0 user so list_my_recent_emails can work.

5. Environment variables

In the project root, create a .env file (see .env.example):

Required (Auth0):

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://your-server.example.com/mcp
RESOURCE_SERVER_URL=https://your-server.example.com/mcp

Optional (Gmail):

GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxx

Optional: GMAIL_TOKEN_STORE_PATH=.gmail_tokens.json (default; where per-user refresh tokens are stored).

6. Run the server

uv run python main.py

Server runs at http://0.0.0.0:8000/mcp (or the URL you use in production, e.g. behind a reverse proxy). MCP clients must send requests with a valid Auth0 access token (Bearer) for your API.

MCP tools

Troubleshooting

• “Gmail is not configured”
  Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env, then use link_my_gmail with a refresh token from scripts/get_gmail_refresh_token.py.

• “redirect_uri_mismatch”
  Add exactly http://localhost:8080/ to your Google OAuth client’s Authorized redirect URIs and save.

• “This app’s request is invalid” / “only developer-approved testers”
  OAuth app is in Testing. In APIs & Services → OAuth consent screen → Test users, add your Gmail address. Or Publish app (you’ll see an “unverified app” warning until verification is done).

• “unauthorized_client” when listing emails
  The refresh token must be from your OAuth client. Get a new one with uv run python scripts/get_gmail_refresh_token.py and call link_my_gmail again.

Tech stack

• FastMCP – MCP server

• Auth0 – OAuth 2.0 for MCP authentication

• Google APIs – Gmail read-only for the linked user

• uv – Python dependency management