Authentication

[thekid]

Goal

Support MCP authentication via OAuth.

Progress

• Server side - see Add possibility to access request values via #[Value] #9, Add OAuth2 gateway to implement authorization for MCP #12 and Pass scopes requested during /authorize #14
• Client side - see Return an Authorization instance from initialize() #3, but still missing a higher-level abstraction

---

Client side

With #3, we can call initialize() and check for an io.modelcontextprotocol.Authorization instance.

Step 1 - Initial request

use io\modelcontextprotocol\{McpClient, Authorization};

$client= new McpClient('http://localhost:3001');
if ($client->initialize() instanceof Authorization) {
  // Start authentication
}

Step 2 - OAuth discovery

Fetch the http://localhost:8080/.well-known/oauth-authorization-server resource
Parse the JSON metadata

Should be provide a fetch() method on the McpClient or should this be abstracted more?

3 - OAuth registration (optional)

Post the registration data
Parse and rember the client ID

{
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:8080/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

4 - Actual authentication

Generate a challenge
(Implementation depends on execution context, e.g. redirect the user)

5 - Token exchange

Once the redirect URL is reached:
With the code received, open /oauth/token and fetch the access token

---

Server side

From the point of view of a server running at mcp.example.com, the following happens:

1 - Initial request

The client makes an unauthenticated request
We respond with a 401 error and the WWW-Authenticate: Bearer header

2 - OAuth discovery

The client requests the URI /.well-known/oauth-authorization-server
We responde with a JSON structure

{
  "issuer": "https://mcp.example.com",
  "authorization_endpoint": "https://mcp.example.com/oauth/authorize",
  "token_endpoint": "https://mcp.example.com/oauth/token",
  "registration_endpoint": "https://mcp.example.com/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"]
}

3 - OAuth registration (optional)

The client registers itself
We store this somewhere and return the client ID

{
  "client_id": "abc123-generated-client-id",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:8080/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

Otherwise, the redirect URI would come from our storage

4 - Actual authentication

The client redirects the user to the /oauth/authorize endpoint using PKCE
We authenticate the user, calculate a one-time code and redirect them back to the requested redirect URI

5 - Token exchange

The client passes the one-time code
We respond with the access token

{
  "access_token": "ey...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...."
}

---

This can be implemented with a server-side session containing the user. The code is put in there during authentication, and removed once the token exchange has finished, preventing replay attacks.

[thekid]

MCP inspector actually tries all of these URIs:

[2025-12-31 11:14:50 25048 1962.898kB] 401 GET /.well-known/oauth-protected-resource/mcp
[2025-12-31 11:14:50 25048 1962.820kB] 401 GET /.well-known/oauth-protected-resource
[2025-12-31 11:14:50 25048 1962.852kB] 401 GET /.well-known/oauth-authorization-server
[2025-12-31 11:14:51 25048 1962.852kB] 401 GET /.well-known/openid-configuration

[thekid]

🧪 Proof of concept: https://gist.github.com/thekid/e6ca3935b82a5e79e3337b1f2c3a596d

• Discovery under the URI /.well-known/oauth-authorization-server
• Dynamic client registration
• Authorize endpoint
• Proxy authentication
• Client and redirect URI verification
• Token endpoint
• PKCE verification with S256 and plain methods
• Access token
• Refresh token

[thekid]

The proxy authentication happens inside step 4:

1. The client redirects the user to the /oauth/authorize endpoint using PKCE
   1. We check whether we know the user using a web.auth.Authentication instance
   2. If not, we invoke the authentication flow and pass /oauth/callback inside the redirect URI
   3. When the authentication flow completes, we fetch the user object and pass it to our session
2. We calculate a one-time code and redirect them back to the requested redirect URI

---

The essence of the implementation is this:

- $session= $sessions->create();
- $session->register('user', 'test');
- 
- return $this->redirect($response, $target);
+ return $auth->filter($request, $response, new Invocation(function($request, $response) use($sessions) {
+   $session= $sessions->create();
+   $session->register('user', $request->value('user'));
+
+   return $this->redirect($response,  $target);
+ });

[thekid]

The following shows an abbreviated example of wiring up the OAuth2 gateway:

use io\modelcontextprotocol\McpServer;
use io\modelcontextprotocol\server\{ImplementationsIn, OAuth2Gateway};
use web\Application;
use web\session\InFileSystem;

class Test extends Application {

  public function routes() {
    $sessions= (new InFileSystem())->named('oauth');

    $tokens= /* a class with issue() and use() */;
    $clients= /* a class with lookup() and register() */;

    $gateway= new OAuth2Gateway('/oauth', $clients, $tokens);
    $auth= /* any web.auth.Authentication instance */;

    $server= new McpServer(new ImplementationsIn('impl'));
    return [
      '/.well-known/oauth-authorization-server' => $gateway->meta(),
      '/oauth' => $gateway->flow($auth, $sessions),
      '/mcp'   => $gateway->authenticate($server),
    ];
  }
}

---

The access_token can be anything, here are two implementations:

Use signed RS256 JWTs

Generate the key pair as follows:

$ openssl genrsa 2048 > private_key.txt
$ openssl rsa -pubout < private_key.txt > public_key.txt

use web\auth\oauth\JWT;

$privateKey= file_get_contents('private_key.txt');
$publicKey= file_get_contents('public_key.txt');
$tokens= new class($privateKey, $publicKey) {

  public function __construct(private $privateKey, private $publicKey) { }

  public function issue($issuer, $audience, $session) {
    $jwt= new JWT(['typ' => 'JWT'], $session->value('user') + [
      'iat' => time(),
      'iss' => $issuer,
      'aud' => $audience,
    ]);
    $session->destroy();
    return ['token_type' => 'Bearer', 'access_token' => $jwt->sign($this->privateKey)];
  }

  public function use($token) {
    return JWT::tryFrom($token, $this->publicKey)?->payload();
  }
};

Reuse authentication sessions

The sessions instance is also passed to $gateway->flow($auth, sessions) in the above application code.

use web\session\{Sessions, InFileSystem};

$sessions= (new InFileSystem($sessions))->named('oauth');
$tokens= new class($sessions) {

  public function __construct(private Sessions $sessions) { }

  public function issue($issuer, $audience, $session) {
    return ['token_type' => 'Bearer', 'access_token' => $session->id()]; 
  }

  public function use($token) {
    if ($session= $this->sessions->open($token)) {
      try {
        return $session->value('user');
      } finally {
        $session->close();
      }
    }
    return null;
  }
};

[thekid]

Here's a CORS filter allowing localhost:* (which the spec doesn't) while not having to allow *:

// Allow direct connections from tools running on localhost on any port
$cors= new class() implements Filter {
  public function filter($request, $response, $invokation) {
    $origin= $request->header('Origin');
    $allow= preg_match('/^https?:\/\/localhost(:[0-9]+)$/', $origin) ? $origin : '';

    $response->header('Access-Control-Allow-Origin', $allow);
    $response->header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    $response->header('Access-Control-Max-Age', '86400');

    if ('OPTIONS' === $request->method()) {
      $response->answer(200);
      return;
    }

    return $invokation->proceed($request, $response);
  }
};

[thekid]

Succesfully verified integration with Claude desktop with an MCP server configured as follows:

{
  "mcpServers": {
    "localhost": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp"
      ]
    }
  }
}

$APPDATA/Claude/logs/mcp-server-localhost.log

Invoking an MCP tool

[thekid]

TODO: Implement the "(MCP) protected resource" metadata, see https://blog.christianposta.com/understanding-mcp-authorization-with-dynamic-client-registration/

---

Done in bfc9d3c. This is how it now looks from server-side perspective when Claude Desktop accesses our server running on localhost:8080:

What's next is to actually use these scopes.

[thekid]

First implementation released in 0.8.0

Example: https://github.com/xp-forge/mcp?tab=readme-ov-file#authentication

[thekid]

When delegating to an external authentication mechanism, the /oauth/authorize gets hit twice, creating two sessions, one of which is unnecessary. We might be able to use request rewriting to /oauth/continuation to prevent this.

[thekid]

What's next is to actually use these scopes.

Implemented in #14

[thekid]

Here's the client part:

use webservices\rest\Endpoint;

$uri= 'https://example.com/mcp';
$client= [
  'client_name'                => 'Example application',
  'redirect_uris'              => ['https://app.example.com/auth/'],
  'grant_types'                => ['authorization_code', 'refresh_token'],
  'response_types'             => ['code'],
  'token_endpoint_auth_method' => 'none',
];

// Step 1: Fetch oauth-protected-resource
$server= new Endpoint(new URI($uri)->base());
$protected= $server->resource('/.well-known/oauth-protected-resource')->get()->optional();
if ($protected) {
  $resource= $protected['resource'];
  $scopes= $protected['scopes_supported'];
  $auth= new Endpoint(current($protected['authorization_servers']));
} else {
  $resource= (string)$server->base();
  $scopes= [];
  $auth= $server;
}

// Step 2: Fetch OAuth metadata
$metadata= $auth->resource('/.well-known/oauth-authorization-server')->get()->value();

// Step 3: Register
$registration= $auth
  ->resource($metadata['registration_endpoint'])
  ->post($client, 'application/json')
  ->value()
;

// Step 4: Now perform the direct
$flow= new OAuth2Flow(
  $metadata['authorization_endpoint'],
  $metadata['token_endpoint'],
  new ByPKCE($registration['client_id'], current(array_intersect(
    ['S256', 'plain'],
    $metadata['code_challenge_methods_supported']
  )))
);
$flow->requesting($scopes)->authenticate($request, $response);