Overview
The Opportunity Zone MCP server uses OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange) for secure authentication. This flow is designed to work with both confidential and public clients.
What you'll need:
- • A registered OAuth client (created in the dashboard)
- • A redirect URI where users will be sent after authorization
- • Your application's client ID and secret
Step-by-Step Implementation
Follow these steps to integrate OAuth 2.0 authentication in your application
Step 1
Register Your Application
First, you need to register your application in the developer dashboard.
Manual Registration
- 1. Sign in to the dashboard
- 2. Click "Create New Client"
- 3. Enter your application name
- 4. Add your redirect URIs (one per line)
- 5. Save your client ID and secret
API Registration
POST https://oz-mcp.vercel.app/api/oauth/register
Content-Type: application/json
{
"client_name": "My Application",
"redirect_uris": [
"https://yourapp.com/callback",
"http://localhost:3000/callback"
]
}Step 2
Generate PKCE Parameters (Recommended)
For enhanced security, especially for public clients, generate PKCE parameters.
JavaScript Example
import crypto from 'crypto';
// Generate code verifier
const codeVerifier = crypto.randomBytes(32).toString('base64url');
// Generate code challenge
const codeChallenge = crypto
.createHash('sha256')
.update(codeVerifier)
.digest('base64url');
// Store codeVerifier for later use
localStorage.setItem('code_verifier', codeVerifier);Step 3
Redirect User to Authorization Server
Redirect the user to the authorization endpoint with the required parameters.
Authorization URL
https://oz-mcp.vercel.app/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&scope=api%3Aread&state=random_state_value&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
Parameters
client_id: Your application's client ID
redirect_uri: Where to redirect after authorization
response_type: Must be "code"
scope: Requested permissions (e.g., "api:read")
state: Random value for security
code_challenge: PKCE code challenge
code_challenge_method: "S256" for SHA256
Step 4
Handle Authorization Response
After the user authorizes your application, they'll be redirected back to your redirect URI.
Success Response
https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=random_state_value
Error Response
https://yourapp.com/callback?error=access_denied&error_description=User+denied+authorization&state=random_state_value
Step 5
Exchange Code for Access Token
Exchange the authorization code for an access token.
Token Request
POST https://oz-mcp.vercel.app/api/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTHORIZATION_CODE &redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET &code_verifier=CODE_VERIFIER
Token Response
{
"access_token": "your_access_token_here",
"token_type": "Bearer",
"expires_in": 31536000
}Step 6
Use Access Token
Use the access token to make authenticated requests to the MCP server.
Authenticated Request
POST https://oz-mcp.vercel.app/api/mcp
Authorization: Bearer your_access_token_here
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "check_opportunity_zone",
"arguments": {
"latitude": "38.8977",
"longitude": "-77.0365"
}
}
}