# MCP App with Authentication

This project implements a secure, database-backed OAuth 2.1 authorization server and MCP App on top of the MCP Python SDK (`MCPServer`). 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](https://dashboard.ngrok.com/get-started/).

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:
   ```bash
   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:
   ```yaml
   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**:
   ```bash
   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](https://console.cloud.google.com/) 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:
```env
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:
```bash
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`:
```bash
cd ui
bun run build
```

---

### 5. Start the MCP Inspector

Run the local MCP Inspector using Bun (bunx) or NPM (npx):
```bash
# 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.

---

## Troubleshooting & Known Issues

### MCP Inspector Sandbox Proxy Error (`ENOENT`)

* **Symptom**: `Sandbox not loaded: ENOENT: no such file or directory, open '.../@modelcontextprotocol/inspector/clients/web/static/sandbox_proxy.html'`
* **Cause**: Certain published `@modelcontextprotocol/inspector` npm releases accidentally excluded the static sandbox proxy files from the package distribution. When launching the inspector via `bunx` or `npx`, the `/sandbox` endpoint fails to locate `sandbox_proxy.html`.
* **Workaround**: Copy `sandbox_proxy.html` into the cached `@modelcontextprotocol/inspector` directory in your system cache (`clients/web/static/sandbox_proxy.html` and `server/static/sandbox_proxy.html`) and restart the inspector.

---

## References

* [MCP Apps Overview](https://modelcontextprotocol.io/extensions/apps/overview)
* [Build an MCP App](https://modelcontextprotocol.io/extensions/apps/build)
* [Understanding Authorization in MCP](https://modelcontextprotocol.io/docs/tutorials/security/authorization)