skills.rest
InverterNetwork
InverterNetworkOFFICIAL
Explore all skills by this author →
Website𝕏@inverternetworkGitHub

mcp-oauth-remote-gateway

Guides manual OAuth 2.1 PKCE token exchange and file-based credential storage for MCP servers on remote gateways.

Updated May 4, 2026
Search Tags:#authentication#oauth#mcp#gateway#pkce#remote-deployment
One-click install
npx skills add https://github.com/InverterNetwork/hermes-agent --skill mcp-oauth-remote-gateway-inverternetwork
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mcp-oauth-remote-gateway
Source: https://github.com/InverterNetwork/hermes-agent/tree/main/optional-skills/mcp/mcp-oauth-remote-gateway
Command: npx skills add https://github.com/InverterNetwork/hermes-agent --skill mcp-oauth-remote-gateway-inverternetwork

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This skill resolves the authentication failure that occurs when running Hermes as a remote gateway, where the built-in OAuth flow cannot capture the callback because the browser redirects to the user's local machine instead of the remote server.

Core Features & Use Cases

  • Manual OAuth Dance: Provides a step-by-step procedure to perform PKCE-based OAuth 2.1 flows manually when automated browser-based callbacks are impossible.
  • Token Injection: Enables the manual creation of token storage files that Hermes recognizes, allowing headless gateways to maintain authenticated sessions.
  • Diagnostic Tools: Includes scripts to smoke-test tokens, identify session revocation, and determine the correct recovery path for stalled MCP connections.

Quick Start

Run the diagnose-oauth-mcp script for your server to determine if you need to perform a manual token refresh or a full re-authorization.

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 authenticate an MCP server on a remote headless gateway when the OAuth redirect fails?▼

To authenticate a remote headless MCP gateway, you must manually perform the OAuth 2.1 PKCE flow and inject the resulting tokens into the server's storage files, bypassing the broken browser redirect loop.

Why does my remote MCP server OAuth callback redirect to my local machine instead of the VPS?▼

The OAuth callback redirects locally because remote headless processes cannot capture loopback redirect URIs, requiring a manual token exchange to establish persistent authenticated sessions for containerized agents.

What is the best way to perform manual OAuth token injection for a headless MCP gateway?▼

The best way to inject OAuth tokens is to manually execute the PKCE challenge, capture the authorization code, and write the exchanged access token directly into the credential storage file recognized by your MCP gateway.

Can I test if my MCP gateway OAuth token is valid or revoked without starting a full session?▼

Yes, you can run diagnostic scripts to smoke-test the OAuth token, identify if the session has been revoked, and determine the correct recovery path for stalled MCP connections.

Do I need to re-authorize the entire OAuth flow if my headless MCP connection stalls?▼

Not always; you should first run the diagnostic script to determine if a manual token refresh is sufficient or if a full re-authorization of the OAuth 2.1 PKCE flow is required for your remote gateway.

Does this manual OAuth approach work for containerized MCP server deployments?▼

Yes, this manual OAuth approach is specifically designed to satisfy the requirement for persistent, secure, and automated MCP connectivity in containerized or VPS-based agent environments where browser callbacks fail.

Related Skills

Explore More Software Engineering Skills→
cxnaivecxnaive

mcp-oauth-remote-gateway

Manually authenticate MCP servers with OAuth 2.1 PKCE on remote gateways.

Community
Advanced
broomvabroomva
3

content-engine-autopilot

Orchestrate browser-based AI generation workflows with Playwright for tools lacking public APIs.

Community
Advanced
paarths-collabpaarths-collab
13

integration-zoom

Configure Zoom Server-to-Server OAuth credentials on a remote Hermes VPS over SSH.

Community
Advanced
benjaminshoemakerbenjaminshoemaker
39

oauth-login

Automate OAuth login for Google and GitHub with local callback and token storage.

Community
Advanced