Skip to main content
Glama
gangadharrr

Local OAuth + MCP Test Server

by gangadharrr
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Local OAuth + MCP Test Server

A tiny local server that reproduces GitHub's real OAuth behavior — including its quirks — so you can test your AI Studio OAuth provider against something you fully control, instead of debugging blind against github.com.

Setup

Plain HTTP. For a public HTTPS URL, put a tunnel (ngrok, cloudflared, tailscale funnel) in front — it terminates TLS at the edge and forwards to this server over loopback HTTP.

npm install
cp .env.example .env   # optional - everything has working defaults
npm run dev            # tsx watch mode (TypeScript, no build step)
# or:
npm run build && npm start   # compile to dist/ then run

Configuration is read from a .env file and validated through a Zod schema at startup. Invalid values produce a structured error report and the process exits before binding the port.

Precedence: shell exports > .env file > built-in defaults — so PORT=9999 npm run dev just works.

Booleans accept true / false / 1 / 0 / yes / no / on / off (case-insensitive). Anything else fails with a clear error.

Server starts on http://0.0.0.0:4587 by default, advertising http://localhost:4587 as its PUBLIC_URL.

Related MCP server: mock-mcp

Environment variables

Server / network

Variable

Default

Purpose

PORT

4587

Listen port

HOST

0.0.0.0

Bind address. Set to 127.0.0.1 for localhost-only.

PUBLIC_URL

http://localhost:PORT

URL this server advertises in protocol metadata (OAuth issuer, resource identifier, discovery doc). Set when behind a tunnel so advertised identifiers match what clients see.

OAuth / MCP

Variable

Default

Purpose

CLIENT_ID / CLIENT_SECRET

test-client / test-secret

Must match what you configure in your OAuth client (e.g. AI Studio).

TOKEN_RESPONSE_MODE

form

form | json | always_json — controls the token endpoint's response format. form mirrors GitHub's real default (returns JSON only when the client sends Accept: application/json); always_json forces JSON regardless.

ISSUE_REFRESH_TOKENS

true

Set false to skip issuing refresh_token alongside access_token.

TOKEN_TTL_SECONDS

3600

Access token lifetime — set low (e.g. 5) to test expiry fast.

REFRESH_TTL_SECONDS

86400

Refresh token lifetime.

ROTATE_REFRESH_TOKENS

true

Each refresh issues a new refresh token and invalidates the old one; set false for "static" refresh tokens.

ENABLE_DISCOVERY

false

Set true to serve RFC 8414 / OIDC discovery metadata at /.well-known/oauth-authorization-server (and /.well-known/openid-configuration). Off by default to mirror GitHub's missing metadata.

ENABLE_DCR

false

Set true to serve POST /register (RFC 7591 Dynamic Client Registration). Off by default — real GitHub has no equivalent.

DISABLE_AUTH

false

Set true to bypass every client-side credential check: bearer-token middleware on /mcp, client_id / client_secret validation on /oauth/token, client_id and redirect_uri registration checks on /oauth/authorize, and code / refresh-token validity. With it on, /oauth/authorize and /oauth/token mint valid tokens for any input; /mcp accepts any request as authenticated. Also forces ENABLE_DISCOVERY and ENABLE_DCR off regardless of their values. Local testing only — do NOT enable this while exposing the server (PUBLIC_URL / ngrok).

DCR_STORE_PATH

.dcr-clients.json

Where dynamically-registered clients are persisted. Set /dev/null to disable persistence.

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • SkyStage MCP Test Server

    mallikarjun-angadi
    F
    license
    Not graded
    quality
    D
    maintenance
    Minimal MCP server for testing SkyStage's self-auth auto-detection feature. It includes tools like ping, echo, server_info, and read_secret, and uses a mock OAuth provider for login.
    -

  • mock-mcp

    it370
    F
    license
    Not graded
    quality
    B
    maintenance
    A minimal local HTTP MCP mock server for development and testing, providing predictable tool responses with OAuth token support and zero dependencies.
    -

  • simple-mcp

    pcparts001
    F
    license
    Not graded
    quality
    B
    maintenance
    A simple HTTP-based MCP server that provides demo tools (get_test_string, echo, check_maintenance), greeting prompts, and test resources, with optional OAuth 2.1 support.
    -