basic-mcp-server-auth

This project is a runnable TypeScript example of how to protect an MCP server using GitHub as an OAuth authorization server. It teaches the full .well-known discovery pattern: how MCP clients like VS Code and IntelliJ find your authorization server automatically, why scopes and grant types matter, and how the browser-based login popup works end-to-end.

The server exposes two MCP tools: get_status (returns server health, Copilot quota usage, and today's locally observed usage) and java_expert_answer (forwards a Java question to a Copilot session with Java-specific instructions).

---

The central teaching in this repo is that an MCP client should never need to be told where to authenticate. Instead, the server publishes discovery documents at well-known paths, and the client figures out everything — authorization server, token endpoint, scopes, and grant types — from those documents alone.

This follows RFC 8414 (OAuth Authorization Server Metadata) and the March 2026 MCP authorization guidance.

The moment a client connects to /mcp without a token, the server challenges it with a WWW-Authenticate header that points to the .well-known URL. From that single URL, the client has everything it needs to drive the OAuth flow, open the browser, and retry the request with a fresh token — all without the user manually configuring anything.

---

This is the server card. It tells a client which MCP version the server speaks, where the MCP endpoint lives, and what kind of authentication is required. A client can fetch this before attempting to connect, or it can discover it after receiving a 401.

{
  "mcp_version": "2025-11-25",
  "server_info": {
    "name": "enterprise-mcp",
    "version":