skills.rest
loteiron
loteironCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

mcp-oauth-remote-gateway

Performs manual OAuth 2.1 PKCE flows for remote MCP servers on headless gateways.

Updated Sep 10, 2026
Search Tags:#authentication#oauth#MCP#headless#pkce#token refresh#remote gateway
One-click install
npx skills add https://github.com/loteiron/ZeusAgent --skill mcp-oauth-remote-gateway-loteiron
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mcp-oauth-remote-gateway
Source: https://github.com/loteiron/ZeusAgent/tree/main/optional-skills/mcp/mcp-oauth-remote-gateway
Command: npx skills add https://github.com/loteiron/ZeusAgent --skill mcp-oauth-remote-gateway-loteiron

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? When ZeusAgent runs as a remote gateway (container, VPS, messaging bot), its built-in MCP OAuth flow fails because the browser redirect to 127.0.0.1 resolves to the user's laptop instead of the remote host, so the authorization code never reaches the agent. This Skill performs the OAuth dance manually and writes tokens into ZeusAgent's expected token storage files. ## Core Features & Use Cases - Manual OAuth 2.1 + PKCE flow: Discovers OAuth metadata via RFC 9728, registers a dynamic client via RFC 7591, builds the authorize URL, and exchanges the pasted callback code for tokens. - Token storage in ZeusAgent's schema: Writes <server>.json and <server>.client.json under $ZEUS_HOME/mcp-tokens/ with correct permissions so /reload-mcp skips the browser flow. - Diagnostic script: scripts/diagnose-oauth-mcp.py smoke-tests stored tokens, attempts refresh, and reports which recovery branch applies (TOKEN_OK, REFRESH_FIXED, SESSION_REVOKED, REFRESH_DEAD). - Use Case: A user runs ZeusAgent as a Telegram bot on Railway and wants to add Linear's OAuth-gated MCP server; this Skill walks through the manual flow and persists tokens without any interactive TTY. ## Quick Start Ask the agent to set up OAuth for a remote MCP server on the headless gateway and paste back the callback URL after authorizing in your browser.

Frequently Asked Questions about mcp-oauth-remote-gateway

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add an OAuth MCP server to a headless remote gateway?▼

Perform the OAuth flow manually: discover the server's OAuth metadata, register a dynamic client, build a PKCE authorize URL, have the user paste back the callback URL, then exchange the code and write tokens into $ZEUS_HOME/mcp-tokens/. A subsequent /reload-mcp finds the cached tokens and skips the browser flow.

Why does MCP OAuth fail on a remote server or container?▼

The built-in flow registers http://127.0.0.1:<port>/callback as the redirect URI and listens inside the remote process. The user's browser resolves 127.0.0.1 to their own laptop, so the authorization code never reaches the gateway and the flow times out.

Can I use a static Bearer token instead of OAuth for MCP servers?▼

Yes, and it is preferred when the provider offers one. Set headers.Authorization to a Bearer token in the mcp_servers config; this avoids the refresh and session-revocation cycle entirely, which is more durable for unattended remote gateways.

Why does my OAuth MCP server stay 'not connected' after token refresh?▼

Either the circuit breaker is tripped (restart the gateway after /reload-mcp) or the provider revoked the session server-side, where refresh succeeds but new tokens still get -32002 'Session expired'. Run scripts/diagnose-oauth-mcp.py to identify which branch applies.

Does this manual OAuth flow work with GitHub Copilot MCP?▼

Not directly, because GitHub does not support RFC 7591 Dynamic Client Registration. Its MCP endpoint uses a pre-registered confidential OAuth App requiring a client_secret in the token exchange, or you can use a Personal Access Token instead.

What should I do when refresh returns invalid_grant?▼

An invalid_grant response means the refresh token is dead server-side and cannot be recovered from the gateway. Re-run the full interactive authorization flow, or switch to a static API key if the provider offers one, as documented for Stripe MCP.

Related Skills

Explore More Software Engineering Skills→
Peterson-BenhamePeterson-Benhame

figma

Fetches Figma design context, screenshots, and assets via the Figma MCP server for code implementation.

Community
Intermediate
LamseyahEliasLamseyahElias

native-mcp

Discover stdio and HTTP MCP servers and register their tools for Hermes Agent.

Community
Advanced
RheasilviaRheasilvia

mcp-oauth-remote-gateway

Execute manual OAuth 2.0 PKCE flows for MCP servers on headless remote infrastructure.

Community
Advanced
MoneyPlugMoneyPlug

auth-guide

Configure third-party API key and OAuth authentication for Notion Workers.

Community
Intermediate