fix(oauth): headless server support + non-standard OAuth providers (Granola)

[mgonto]

Problem

Three related issues prevent mcporter OAuth from working on headless Linux servers and with providers like Granola:

1. scope=mcp:tools rejected by Granola — The hardcoded scope: 'mcp:tools' in client metadata is not in Granola's scopes_supported (email, offline_access, openid, profile), causing an invalid_scope error at the authorize endpoint.

2. xdg-open crash on headless servers — On VPS/CI environments without a desktop, spawning xdg-open emits an unhandled ENOENT error event that crashes the Node process before the OAuth callback server can receive the redirect.

3. Stale client registration with dynamic ports — With dynamic callback ports (the default), each run picks a different port. The previous client registration is cached with the old redirect_uri, so the auth server rejects subsequent requests with invalid_redirect_uri.

Fix

1. Remove hardcoded scope from client metadata. The MCP SDK already derives scope from the server's resource metadata or auth server's scopes_supported.
2. Wrap xdg-open spawn in a try/catch and attach an error handler to swallow ENOENT gracefully.
3. Detect redirect URI mismatch on startup and clear stale client registration so re-registration uses the new URI.

Testing

Tested against Granola's official MCP endpoint (https://mcp.granola.ai/mcp) on a headless Ubuntu VPS. All three issues are resolved and the full OAuth flow completes successfully.

Fixes #67

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c89f3f61ad

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Close callback server on persistence errors

This stale-client check executes after server.listen(...) has already bound a local port, so if readClientInfo() (or the later clear('client')) throws due to malformed cache JSON or filesystem permissions, PersistentOAuthClientProvider.create exits without closing the HTTP server. In that failure path the process can be left with an open callback listener and may hang instead of terminating cleanly; wrap this section so failures close the server before rethrowing.

Useful? React with 👍 / 👎.

[alextnetto]

Yes, need that as well. Thanks @mgonto

[tknecht]

Hey @mgonto, nice work on this — removing the hardcoded scope and letting the SDK derive it is definitely the cleaner fix. The headless xdg-open and stale registration fixes are a bonus.

One thing that might be worth tacking on: servers that don't advertise scopes_supported in their metadata would still leave users stuck, since the SDK has nothing to derive from. We ran into a related case and put together a small oauthScope config field as an explicit escape hatch:

{
  "mcpServers": {
    "granola": {
      "baseUrl": "https://mcp.granola.ai/mcp",
      "auth": "oauth",
      "oauthScope": "openid email profile offline_access"
    }
  }
}

The metadata change would just be:

...(definition.oauthScope \!== undefined
  ? { scope: definition.oauthScope || undefined }
  : {}),  // no scope set → SDK derives it as normal

Totally additive on top of what you have. Happy to add it to this branch or follow up after merge — whatever works for you.

[mgonto]

that's awesome. feel free to add it to this branch

[tknecht]

Tried to push directly to your branch but don't have write access to your fork. Here's the diff — should be a straightforward apply:

```diff
diff --git a/src/config-normalize.ts b/src/config-normalize.ts
--- a/src/config-normalize.ts
+++ b/src/config-normalize.ts
@@ -15,6 +15,7 @@ export function normalizeServerEntry(
const tokenCacheDir = normalizePath(raw.tokenCacheDir ?? raw.token_cache_dir);
const clientName = raw.clientName ?? raw.client_name;
const oauthRedirectUrl = raw.oauthRedirectUrl ?? raw.oauth_redirect_url ?? undefined;

• const oauthScope = raw.oauthScope ?? raw.oauth_scope ?? undefined;
  const oauthCommandRaw = raw.oauthCommand ?? raw.oauth_command;
  @@ -58,6 +59,7 @@ export function normalizeServerEntry(
  tokenCacheDir,
  clientName,
  oauthRedirectUrl,
• oauthScope,
  oauthCommand: defaultedOauthCommand,

diff --git a/src/config-schema.ts b/src/config-schema.ts
--- a/src/config-schema.ts
+++ b/src/config-schema.ts
@@ -62,6 +62,8 @@ export const RawEntrySchema = z.object({
oauthRedirectUrl: z.string().optional(),
oauth_redirect_url: z.string().optional(),

• oauthScope: z.string().optional(),
• oauth_scope: z.string().optional(),
  @@ -133,6 +135,7 @@ export interface ServerDefinition {
  readonly clientName?: string;
  readonly oauthRedirectUrl?: string;
• readonly oauthScope?: string;

diff --git a/src/oauth.ts b/src/oauth.ts
--- a/src/oauth.ts
+++ b/src/oauth.ts
@@ -88,6 +88,9 @@ class PersistentOAuthClientProvider implements OAuthClientProvider {
// Hardcoding 'mcp:tools' breaks providers like Granola whose auth server
// does not recognise that scope value.

•  // If the user explicitly sets oauthScope in their config, use it as an
  

•  // escape hatch for servers that don't advertise scopes_supported.
  

•  ...(definition.oauthScope !== undefined ? { scope: definition.oauthScope || undefined } : {}),
  

  };
  }
  ```

Three files touched, all additive. Typechecks clean.

[mansilladev]

@steipete Can you please merge this in, or at least cherry pick the dynamic port issue fix?

[steipete]

Landed via temp rebase onto main.

• Gate: pnpm check && pnpm test && pnpm build && pnpm run docs:list
• Land commit: 779d560
• Merge commit: 98c300b

Thanks @mgonto!