|
| 1 | +--- |
| 2 | +title: Getting Started |
| 3 | +--- |
| 4 | + |
| 5 | +This guide will help you quickly get MCP OAuth Proxy up and running. |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +- Docker installed on your system |
| 10 | +- An OAuth provider account (Google, Microsoft, GitHub, etc.) |
| 11 | +- A running MCP server to proxy to |
| 12 | + |
| 13 | +## Quick Start |
| 14 | + |
| 15 | +### 1. Setup OAuth Credentials |
| 16 | + |
| 17 | +OAuth credentials (Client ID and Client Secret) are used by the proxy to authenticate with external providers on behalf of your users. When users sign in, the proxy uses these credentials to verify their identity and obtain access tokens for external services. |
| 18 | + |
| 19 | +#### Google OAuth |
| 20 | + |
| 21 | +1. **Create Project**: Go to [Google Cloud Console](https://console.cloud.google.com/) and create a new project or select an existing one |
| 22 | +2. **Enable APIs**: In the API & Services dashboard, click "Enable APIs and Services" and enable: |
| 23 | + - Google+ API (for basic profile info) |
| 24 | + - Any additional APIs your MCP server needs (Gmail, Drive, etc.) |
| 25 | +3. **Configure OAuth Consent Screen**: |
| 26 | + - Go to "OAuth consent screen" in the sidebar |
| 27 | + - Go to "Audience" |
| 28 | + - Choose "External" for user type |
| 29 | + - Add users email address that you authorize to use the application |
| 30 | +4. **Create OAuth Client**: |
| 31 | + - Go to "Credentials" in the sidebar |
| 32 | + - Click "Create Credentials" > "OAuth 2.0 Client IDs" |
| 33 | + - Choose "Web application" as application type |
| 34 | + - Give your client a name (e.g., "MCP OAuth Proxy") |
| 35 | + - Under "Authorized JavaScript origins", add: `http://localhost:8080` |
| 36 | + - Under "Authorized redirect URIs", add: `http://localhost:8080/callback` |
| 37 | + - Click "Create" |
| 38 | + - A dialog will show your **Client ID** and **Client Secret** - copy both immediately. You will need to use these in the next step. |
| 39 | + |
| 40 | +#### Microsoft OAuth |
| 41 | + |
| 42 | +1. **Azure Portal**: Go to [Azure Portal](https://portal.azure.com/). |
| 43 | +2. **App Registration**: |
| 44 | + - Click "App registrations" > "New registration" |
| 45 | + - Name your application |
| 46 | + - Set redirect URI to `http://localhost:8080/callback` |
| 47 | + - Click "Register" |
| 48 | +3. **Configure Permissions**: |
| 49 | + - Go to "API permissions" |
| 50 | + - Add permissions for Microsoft Graph (e.g., `User.Read`, `Mail.Read`) |
| 51 | +4. **Create Secret**: |
| 52 | + - Go to "Certificates & secrets" |
| 53 | + - Click "New client secret" |
| 54 | + - Copy the **Client Secret** (save immediately - it won't be shown again) |
| 55 | + - Copy the **Application (client) ID** from the Overview page |
| 56 | + |
| 57 | +#### GitHub OAuth |
| 58 | + |
| 59 | +1. **GitHub Settings**: Go to GitHub Settings > Developer settings > [OAuth Apps](https://github.com/settings/applications/new) |
| 60 | +2. **Create OAuth App**: |
| 61 | + - **Application name**: Your app name |
| 62 | + - **Homepage URL**: Your application's homepage |
| 63 | + - **Authorization callback URL**: `http://localhost:8080/callback` |
| 64 | + - **Application description**: Optional description |
| 65 | +3. **Get Credentials**: |
| 66 | + - Click "Register application" |
| 67 | + - Copy your **Client ID** |
| 68 | + - Generate a **Client Secret** and copy it immediately |
| 69 | + |
| 70 | +### 2. Setup Your MCP Server |
| 71 | + |
| 72 | +The OAuth proxy requires a streamable HTTP MCP server to proxy requests to. Your MCP server must: |
| 73 | + |
| 74 | +- **Support Streamable HTTP transport** - Accept HTTP requests (not just stdio) |
| 75 | +- **Be accessible** - Running and reachable from the proxy container |
| 76 | + |
| 77 | +**Example MCP Server Setup:** |
| 78 | + |
| 79 | +```bash |
| 80 | +# Example using Obot's Gmail MCP server |
| 81 | +git clone https://github.com/obot-platform/tools |
| 82 | +cd google/gmail |
| 83 | +uv run python -m obot_gmail_mcp.server |
| 84 | +``` |
| 85 | + |
| 86 | +This will start the server at http://localhost:9000/mcp/gmail. |
| 87 | + |
| 88 | +:::note |
| 89 | +If you are using gmail mcp server, make sure you setup google oauth credentials as described in the [Google OAuth](#google-oauth) section. |
| 90 | +::: |
| 91 | + |
| 92 | +### 3. Run OAuth Proxy |
| 93 | + |
| 94 | +:::note |
| 95 | +Different Auth provider have different authorize urls. Make sure you use the correct one for your auth provider. Here is a list of authorize urls for different auth providers: |
| 96 | + |
| 97 | +- Google: https://accounts.google.com |
| 98 | +- Microsoft: https://login.microsoftonline.com/common/oauth2/v2.0/authorize |
| 99 | +- GitHub: https://github.com/login/oauth/authorize |
| 100 | + |
| 101 | +Make sure you are supplying the correct authorize url in the environment variables `OAUTH_AUTHORIZE_URL`. |
| 102 | + |
| 103 | +::: |
| 104 | + |
| 105 | +#### Option A: Docker |
| 106 | + |
| 107 | +```bash |
| 108 | +docker run -d --name mcp-oauth-proxy -p 8080:8080 \ |
| 109 | + -e OAUTH_CLIENT_ID="your-client-id" \ |
| 110 | + -e OAUTH_CLIENT_SECRET="your-client-secret" \ |
| 111 | + -e OAUTH_AUTHORIZE_URL="https://accounts.google.com" \ |
| 112 | + -e SCOPES_SUPPORTED="openid,email,profile,https://www.googleapis.com/auth/gmail.readonly" \ |
| 113 | + -e MCP_SERVER_URL="http://localhost:9000/mcp/gmail" \ |
| 114 | + ghcr.io/obot-platform/mcp-oauth-proxy:latest |
| 115 | +``` |
| 116 | + |
| 117 | +#### Option B: CLI Binary |
| 118 | + |
| 119 | +1. **Download Latest Release**: |
| 120 | + |
| 121 | + - Go to [GitHub Releases](https://github.com/obot-platform/mcp-oauth-proxy/releases) |
| 122 | + - Download the appropriate binary for your platform (Linux, macOS, Windows) |
| 123 | + |
| 124 | +2. **Run with Environment Variables**: |
| 125 | + |
| 126 | + ```bash |
| 127 | + # Set environment variables |
| 128 | + export OAUTH_CLIENT_ID="your-client-id" |
| 129 | + export OAUTH_CLIENT_SECRET="your-client-secret" |
| 130 | + export OAUTH_AUTHORIZE_URL="https://accounts.google.com" |
| 131 | + export SCOPES_SUPPORTED="openid,email,profile,https://www.googleapis.com/auth/gmail.readonly" |
| 132 | + export MCP_SERVER_URL="http://localhost:9000/mcp/gmail" |
| 133 | + |
| 134 | + # Run the binary |
| 135 | + ./mcp-oauth-proxy |
| 136 | + ``` |
| 137 | + |
| 138 | +## Environment Variables |
| 139 | + |
| 140 | +| Variable | Required | Description | |
| 141 | +| --------------------- | -------- | --------------------------------------------------------- | |
| 142 | +| `OAUTH_CLIENT_ID` | ✅ | OAuth client ID from provider | |
| 143 | +| `OAUTH_CLIENT_SECRET` | ✅ | OAuth client secret | |
| 144 | +| `OAUTH_AUTHORIZE_URL` | ✅ | Provider's base URL (e.g., `https://accounts.google.com`) | |
| 145 | +| `SCOPES_SUPPORTED` | ✅ | Comma-separated OAuth scopes | |
| 146 | +| `MCP_SERVER_URL` | ✅ | Your MCP server endpoint | |
| 147 | +| `DATABASE_DSN` | ❌ | Database connection string (defaults to SQLite) | |
| 148 | +| `ENCRYPTION_KEY` | ✅ | Base64-encoded 32-byte AES key | |
| 149 | + |
| 150 | +:::note |
| 151 | +You can generate a random encryption key using the following command: |
| 152 | + |
| 153 | +```bash |
| 154 | +openssl rand -base64 32 |
| 155 | +``` |
| 156 | + |
| 157 | +Make sure you are storing the encryption key in a secure way. |
| 158 | + |
| 159 | +::: |
| 160 | + |
| 161 | +:::note |
| 162 | +By default, you can use the proxy with sqlite database and it will store the db locally in a file called `oauth-proxy.db`. |
| 163 | + |
| 164 | +In production, it is recommended to use postgres database. You can use the following command to create a postgres database: |
| 165 | + |
| 166 | +```bash |
| 167 | +docker run -d --name mcp-oauth-proxy-postgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=oauth-proxy postgres |
| 168 | +``` |
| 169 | + |
| 170 | +Then you can set the `DATABASE_DSN` environment variable to the connection string of your postgres database. |
| 171 | +For example: |
| 172 | + |
| 173 | +```bash |
| 174 | +DATABASE_DSN="postgresql://postgres:postgres@localhost:5432/oauth-proxy" |
| 175 | +``` |
| 176 | + |
| 177 | +::: |
| 178 | + |
| 179 | +## Verification |
| 180 | + |
| 181 | +You can now test your setup by using vscode MCP. |
| 182 | + |
| 183 | +1. **Create Workspace Configuration**: Create a `.vscode/mcp.json` file in your workspace folder: |
| 184 | + |
| 185 | +```json |
| 186 | +{ |
| 187 | + "servers": { |
| 188 | + "oauth-gmail": { |
| 189 | + "type": "http", |
| 190 | + "url": "http://localhost:8080/mcp/gmail" |
| 191 | + } |
| 192 | + } |
| 193 | +} |
| 194 | +``` |
| 195 | + |
| 196 | +4. **Authentication Flow**: |
| 197 | + |
| 198 | +- When VSCode first connects, it will open a browser for OAuth authentication |
| 199 | +- Sign in with your Google account |
| 200 | +- Grant the requested permissions |
| 201 | +- VSCode will receive the access token and can now communicate with the Gmail MCP server |
| 202 | + |
| 203 | +5. **Test the Connection**: |
| 204 | + |
| 205 | +- Open copilot panel in vscode |
| 206 | +- prompt to get the list of emails |
| 207 | +- you should see the list of emails |
| 208 | + |
| 209 | +## Troubleshooting |
| 210 | + |
| 211 | +If you are facing any issues, you can check the logs of the proxy by running the following command: |
| 212 | + |
| 213 | +```bash |
| 214 | +docker logs mcp-oauth-proxy |
| 215 | +``` |
0 commit comments