Step 1: Client sends request to MCP Server endpoint
        -> Server returns 401 Unauthorized

Step 2: Client fetches Protected Resource Metadata (RFC 9728)
        GET https://mcp-server.example.com/.well-known/oauth-protected-resource
        -> Obtains authorization_servers list

Step 3: Client fetches Authorization Server Metadata (RFC 8414)
        GET https://auth.example.com/.well-known/oauth-authorization-server
        -> Obtains authorization_endpoint, token_endpoint, etc.

Step 4: Dynamic Client Registration (RFC 7591, if needed)
        POST https://auth.example.com/register
        -> Obtains client_id (no client_secret, as this is a public client)

Step 5: Authorization Code + PKCE (S256)
        a. Client generates code_verifier and code_challenge
        b. Guides user to the authorization_endpoint
        c. User authorizes, Client obtains authorization_code
        d. Client exchanges code + code_verifier for access_token

Step 6: Subsequent requests carry Bearer Token
        POST https://mcp-server.example.com/mcp
        Authorization: Bearer eyJhbG...
        Mcp-Session-Id: session-abc123

// 1. Client generates a random code_verifier
code_verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

// 2. Compute code_challenge = BASE64URL(SHA256(code_verifier))
code_challenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

// 3. Authorization request includes code_challenge
GET /authorize?
  response_type=code&
  client_id=my-client&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256&
  redirect_uri=http://localhost:8080/callback

// 4. Token exchange includes code_verifier
POST /token
  grant_type=authorization_code&
  code=AUTH_CODE&
  code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

import express from "express";

const app = express();

// OAuth token verification middleware
async function authenticate(req, res, next) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) {
    // Return 401, guiding the Client to perform OAuth authentication
    return res.status(401).json({
      error: "unauthorized"
    });
  }

  // Verify token (call authorization server introspection endpoint or local JWT verification)
  const user = await verifyToken(token);
  if (!user) return res.status(403).json({ error: "invalid_token" });

  req.user = user;
  next();
}

// Protected Resource Metadata endpoint (RFC 9728)
app.get("/.well-known/oauth-protected-resource", (req, res) => {
  res.json({
    resource: "https://mcp-server.example.com",
    authorization_servers: ["https://auth.example.com"],
    bearer_methods_supported: ["header"]
  });
});

// MCP endpoint (authentication required)
app.post("/mcp", authenticate, async (req, res) => {
  const result = await handleMcpRequest(req.body, req.user);
  res.json(result);
});

// Check permissions during tool execution
server.tool("create_return", "Initiate a return", schema, async (args, context) => {
  // Check if the user has permission to operate on this order
  const order = await db.orders.findById(args.orderId);
  if (order.userId !== context.user.id) {
    return {
      content: [{ type: "text", text: "No permission to operate on this order" }],
      isError: true
    };
  }
  // Execute return logic
  const returnRequest = await db.returns.create({
    orderId: args.orderId,
    reason: args.reason,
    userId: context.user.id
  });
  return {
    content: [{
      type: "text",
      text: `Return request created: ${returnRequest.id}`
    }]
  };
});

{
  "uri": "commerce://analytics/daily",
  "annotations": {
    "audience": ["assistant"],
    "priority": 0.3
  }
}