Skip to content

Make authorizationUrl and launch exclusive #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
koistya merged 5 commits into from
Jan 24, 2026
Merged

Make authorizationUrl and launch exclusive #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
96252b1
Fix: Make authorizationUrl and launch exclusive
mina-asham Jan 24, 2026
dfbcb40
fix: enforce two-mode API for getAuthCode options
koistya Jan 24, 2026
e7d4b04
style: format code
koistya Jan 24, 2026
5e4ad18
chore: bump version to 2.1.0
koistya Jan 24, 2026
7c32c9a
fix: add missing launch option to browserAuth examples
koistya Jan 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
const authProvider = browserAuth({
port: 3000,
scope: "read write",
launch: open, // Opens browser for OAuth consent
store: inMemoryStore(), // Or fileStore() for persistence
});

Expand All @@ -155,17 +156,20 @@ import { browserAuth, inMemoryStore, fileStore } from "oauth-callback/mcp";

// Ephemeral storage (tokens lost on restart)
const ephemeralAuth = browserAuth({
launch: open,
store: inMemoryStore(),
});

// Persistent file storage (default: ~/.mcp/tokens.json)
const persistentAuth = browserAuth({
launch: open,
store: fileStore(),
storeKey: "my-app-tokens", // Namespace for multiple apps
});

// Custom file location
const customAuth = browserAuth({
launch: open,
store: fileStore("/path/to/tokens.json"),
});
```
Expand All @@ -179,6 +183,7 @@ const authProvider = browserAuth({
clientId: "your-client-id",
clientSecret: "your-client-secret",
scope: "read write",
launch: open, // Opens browser for OAuth consent
store: fileStore(), // Persist tokens across sessions
});
```
Expand Down Expand Up @@ -283,6 +288,7 @@ Available from `oauth-callback/mcp`. Creates an MCP SDK-compatible OAuth provide
- `clientSecret` (string): Pre-registered client secret (optional)
- `store` (TokenStore): Token storage implementation (default: inMemoryStore())
- `storeKey` (string): Storage key for tokens (default: "mcp-tokens")
- `launch` (function): Callback to launch auth URL (e.g., `open`)
- `authTimeout` (number): Authorization timeout in ms (default: 300000)
- `successHtml` (string): Custom success page HTML
- `errorHtml` (string): Custom error page HTML
Expand Down
56 changes: 53 additions & 3 deletions docs/api/browser-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,9 +96,11 @@ await client.connect(transport);
Store tokens across sessions:

```typescript
import open from "open";
import { browserAuth, fileStore } from "oauth-callback/mcp";

const authProvider = browserAuth({
launch: open,
store: fileStore(), // Persists to ~/.mcp/tokens.json
scope: "read write",
});
Expand All @@ -111,10 +113,13 @@ const authProvider = browserAuth({
If you have pre-registered OAuth credentials:

```typescript
import open from "open";

const authProvider = browserAuth({
clientId: process.env.OAUTH_CLIENT_ID,
clientSecret: process.env.OAUTH_CLIENT_SECRET,
scope: "read write admin",
launch: open,
store: fileStore(),
});
```
Expand All @@ -124,9 +129,11 @@ const authProvider = browserAuth({
Store tokens in a specific location:

```typescript
import open from "open";
import { browserAuth, fileStore } from "oauth-callback/mcp";

const authProvider = browserAuth({
launch: open,
store: fileStore("/path/to/my-tokens.json"),
storeKey: "my-app-production", // Namespace for multiple environments
});
Expand All @@ -137,10 +144,13 @@ const authProvider = browserAuth({
Configure the callback server:

```typescript
import open from "open";

const authProvider = browserAuth({
port: 8080,
hostname: "127.0.0.1",
callbackPath: "/oauth/callback",
launch: open,
store: fileStore(),
});
```
Expand All @@ -157,7 +167,10 @@ Ensure your OAuth app's redirect URI matches your configuration:
Provide branded callback pages:

```typescript
import open from "open";

const authProvider = browserAuth({
launch: open,
successHtml: `
<!DOCTYPE html>
<html>
Expand Down Expand Up @@ -208,7 +221,10 @@ const authProvider = browserAuth({
Monitor OAuth flow for debugging:

```typescript
import open from "open";

const authProvider = browserAuth({
launch: open,
onRequest: (req) => {
const url = new URL(req.url);
console.log(`[OAuth] ${req.method} ${url.pathname}`);
Expand Down Expand Up @@ -263,9 +279,12 @@ sequenceDiagram
No pre-registration needed:

```typescript
import open from "open";

// No clientId or clientSecret required!
const authProvider = browserAuth({
scope: "read write",
launch: open,
store: fileStore(), // Persist dynamically registered client
});

Expand Down Expand Up @@ -317,9 +336,11 @@ interface OAuthStore extends TokenStore {
Ephemeral storage (tokens lost on restart):

```typescript
import open from "open";
import { browserAuth, inMemoryStore } from "oauth-callback/mcp";

const authProvider = browserAuth({
launch: open,
store: inMemoryStore(),
});
```
Expand All @@ -335,15 +356,18 @@ const authProvider = browserAuth({
Persistent storage to JSON file:

```typescript
import open from "open";
import { browserAuth, fileStore } from "oauth-callback/mcp";

// Default location: ~/.mcp/tokens.json
const authProvider = browserAuth({
launch: open,
store: fileStore(),
});

// Custom location
const customAuth = browserAuth({
launch: open,
store: fileStore("/path/to/tokens.json"),
});
```
Expand Down Expand Up @@ -388,6 +412,7 @@ class RedisStore implements TokenStore {

// Use custom store
const authProvider = browserAuth({
launch: open,
store: new RedisStore(redisClient),
});
```
Expand All @@ -409,8 +434,10 @@ PKCE prevents authorization code interception attacks by:
The provider automatically generates secure state parameters:

```typescript
import open from "open";

// State is automatically generated and validated
const authProvider = browserAuth();
const authProvider = browserAuth({ launch: open });
// No manual state handling needed!
```

Expand All @@ -430,8 +457,11 @@ Tokens are automatically managed with expiry tracking:
File storage uses restrictive permissions:

```typescript
import open from "open";

// Files are created with mode 0600 (owner read/write only)
const authProvider = browserAuth({
launch: open,
store: fileStore(), // Secure file permissions
});
```
Expand Down Expand Up @@ -472,7 +502,10 @@ The provider includes automatic retry for transient failures:
Configure timeout for different scenarios:

```typescript
import open from "open";

const authProvider = browserAuth({
launch: open,
authTimeout: 600000, // 10 minutes for first-time setup
});
```
Expand All @@ -484,13 +517,15 @@ const authProvider = browserAuth({
Full example with Dynamic Client Registration:

```typescript
import open from "open";
import { browserAuth, fileStore } from "oauth-callback/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

async function connectToNotion() {
// No client credentials needed - uses DCR!
const authProvider = browserAuth({
launch: open, // Opens browser for OAuth consent
store: fileStore(), // Persist tokens and client registration
scope: "read write",
onRequest: (req) => {
Expand Down Expand Up @@ -536,24 +571,28 @@ connectToNotion();
Support development, staging, and production:

```typescript
import { browserAuth, fileStore } from "oauth-callback/mcp";
import open from "open";
import { browserAuth, fileStore, inMemoryStore } from "oauth-callback/mcp";

function createAuthProvider(environment: "dev" | "staging" | "prod") {
const configs = {
dev: {
port: 3000,
launch: open,
store: inMemoryStore(), // No persistence in dev
authTimeout: 60000,
onRequest: (req) => console.log("[DEV]", req.url),
onRequest: (req: Request) => console.log("[DEV]", req.url),
},
staging: {
port: 3001,
launch: open,
store: fileStore("~/.mcp/staging-tokens.json"),
storeKey: "staging",
authTimeout: 120000,
},
prod: {
port: 3002,
launch: open,
store: fileStore("~/.mcp/prod-tokens.json"),
storeKey: "production",
authTimeout: 300000,
Expand All @@ -576,9 +615,11 @@ const authProvider = createAuthProvider(
While automatic refresh is pending full implementation, you can handle expired tokens:

```typescript
import open from "open";
import { browserAuth, fileStore } from "oauth-callback/mcp";

const authProvider = browserAuth({
launch: open,
store: fileStore(),
scope: "offline_access", // Request refresh token
});
Expand Down Expand Up @@ -701,8 +742,11 @@ describe("OAuth Flow Integration", () => {
::: details Port Already in Use

```typescript
import open from "open";

// Use a different port
const authProvider = browserAuth({
launch: open,
port: 8080, // Try alternative port
});
```
Expand All @@ -712,8 +756,11 @@ const authProvider = browserAuth({
::: details Tokens Not Persisting

```typescript
import open from "open";

// Ensure you're using file store, not in-memory
const authProvider = browserAuth({
launch: open,
store: fileStore(), // ✅ Persistent
// store: inMemoryStore() // ❌ Lost on restart
});
Expand All @@ -725,8 +772,11 @@ const authProvider = browserAuth({
Some servers may not support Dynamic Client Registration:

```typescript
import open from "open";

// Fallback to pre-registered credentials
const authProvider = browserAuth({
launch: open,
clientId: "your-client-id",
clientSecret: "your-client-secret",
});
Expand Down
Loading