Merge pull request #33 from laravel/ai-121-sanctum-auth-works-great

feat: tested Sanctum support

Author: ashleyhindle

.DS_Store

@@ -4,3 +4,4 @@
 /phpunit.xml
 /.phpunit.cache
 .claude
+.DS_Store

.gitignore

@@ -338,27 +338,68 @@ php artisan mcp:start demo
 
 ## Authentication
 
-Web-based MCP servers can be protected using [Laravel Passport](https://laravel.com/docs/passport), turning your MCP server into an OAuth2 protected resource.
+### OAuth 2.1
 
-If you already have Passport set up for your app, all you need to do is add the `Mcp::oauthRoutes()` helper to your `routes/web.php` file. This registers the required OAuth2 discovery and client registration endpoints. The method accepts an optional route prefix, which defaults to `oauth`.
+The recommended way to protect your web-based MCP servers is to
+use [Laravel Passport](https://laravel.com/docs/passport), turning your MCP server into an OAuth2 protected resource.
+
+If you already have Passport set up for your app, all you need to do is add the `Mcp::oauthRoutes()` helper to your
+`routes/web.php` file. This registers the required OAuth2 discovery and client registration endpoints.
+
+To secure, apply Passport's `auth:api` middleware to your server registration in `routes/ai.php`:
 
 ```php
+use App\Mcp\Servers\WeatherExample;
 use Laravel\Mcp\Facades\Mcp;
 
 Mcp::oauthRoutes();
+
+Mcp::web('/mcp/weather', WeatherExample::class)
+    ->middleware('auth:api');
 ```
 
-Then, apply the `auth:api` middleware to your server registration in `routes/ai.php`:
+### Sanctum
+
+If you'd like to protect your MCP server using Sanctum, simply add the Sanctum middleware to your server in
+`routes/ai.php`. Make sure MCP clients pass the usual `Authorization: Bearer token` header.
 
 ```php
 use App\Mcp\Servers\WeatherExample;
 use Laravel\Mcp\Facades\Mcp;
 
-Mcp::web('/mcp/weather', WeatherExample::class)
-    ->middleware('auth:api');
+Mcp::web('/mcp/demo', WeatherExample::class)
+    ->middleware('auth:sanctum');
+```
+
+## Authorization
+
+Type hint `Authenticatable` in your primitives, or use `$request->user()` to check authorization.
+
+```php
+public function handle(Request $request, Authenticatable $user) view.
+{
+  if ($user->tokenCan('server:update') === false) {
+    return ToolResult::error('Permission denied');
+  }
+  
+  if ($request->user()->can('check:weather') === false) {
+    return ToolResult::error('Permission denied');
+  }
+  ...
+}
 ```
 
-Your MCP server is now protected using OAuth.
+### Conditionally registering tools
+
+You can hide tools from certain users without modifying your server config by using `shouldRegister`.
+
+```php
+/** UpdateServer tool **/
+public function shouldRegister(Authenticatable $user): bool
+{
+  return $user->tokenCan('server:update');
+}
+```
 
 ## Testing Servers With the MCP Inspector Tool
 

README.md

@@ -6,6 +6,8 @@
 
 use Exception;
 use Illuminate\Console\Command;
+use Illuminate\Routing\Route;
+use Illuminate\Support\Arr;
 use Laravel\Mcp\Server\Registrar;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Input\InputArgument;
@@ -31,14 +33,33 @@ public function handle(Registrar $registrar): int
         $this->components->info("Starting the MCP Inspector for server [{$handle}]");
 
         $localServer = $registrar->getLocalServer($handle);
-        $webServer = $registrar->getWebServer($handle);
+        $route = $registrar->getWebServer($handle);
 
-        if (is_null($localServer) && is_null($webServer)) {
-            $this->components->error("MCP Server with name [{$handle}] not found. Did you register it using [Mcp::local()] or [Mcp::web()]?");
+        $servers = $registrar->servers();
+        if ($servers === []) {
+            $this->components->error('No MCP servers found. Please run `php artisan make:mcp-server [name]`');
 
             return static::FAILURE;
         }
 
+        // Only one server, we should just run it for them
+        if (count($servers) === 1) {
+            $server = array_shift($servers);
+            [$localServer, $route] = match (true) {
+                is_callable($server) => [$server, null],
+                $server::class === Route::class => [null, $server],
+                default => [null, null],
+            };
+        }
+
+        if (is_null($localServer) && is_null($route)) {
+            $this->components->error('Please pass a valid MCP handle or route: '.Arr::join(array_keys($servers), ', '));
+
+            return static::FAILURE;
+        }
+
+        $env = [];
+
         if ($localServer !== null) {
             $artisanPath = base_path('artisan');
 
@@ -60,11 +81,17 @@ public function handle(Registrar $registrar): int
                 ]),
             ];
         } else {
-            $serverUrl = str_replace('https://', 'http://', route('mcp-server.'.$handle));
+            $serverUrl = url($route->uri());
+            if (parse_url($serverUrl, PHP_URL_SCHEME) === 'https') {
+                $env['NODE_TLS_REJECT_UNAUTHORIZED'] = '0';
+            }
 
             $command = [
                 'npx',
                 '@modelcontextprotocol/inspector',
+                '--transport',
+                'http',
+                '--server-url',
                 $serverUrl,
             ];
 
@@ -75,7 +102,7 @@ public function handle(Registrar $registrar): int
             ];
         }
 
-        $process = new Process($command);
+        $process = new Process($command, null, $env);
         $process->setTimeout(null);
 
         try {
@@ -103,7 +130,7 @@ public function handle(Registrar $registrar): int
     protected function getArguments(): array
     {
         return [
-            ['handle', InputArgument::REQUIRED, 'The handle of the MCP server to inspect.'],
+            ['handle', InputArgument::REQUIRED, 'The handle or route of the MCP server to inspect.'],
         ];
     }
 

src/Console/Commands/InspectorCommand.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class AddWwwAuthenticateHeader
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  Closure(\Illuminate\Http\Request): (\Illuminate\Http\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        $response = $next($request);
+        if ($response->getStatusCode() !== 401) {
+            return $response;
+        }
+
+        $isOauth = app('router')->has('mcp.oauth.protected-resource');
+        if ($isOauth) {
+            $response->header(
+                'WWW-Authenticate',
+                'Bearer realm="mcp", resource_metadata="'.route('mcp.oauth.protected-resource').'"'
+            );
+
+            return $response;
+        }
+
+        // Sanctum, can't share discover URL
+        $response->header(
+            'WWW-Authenticate',
+            'Bearer realm="mcp", error="invalid_token"'
+        );
+
+        return $response;
+    }
+}

src/Server/Middleware/AddWwwAuthenticateHeader.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class ReorderJsonAccept
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        $accept = $request->header('Accept');
+        if (is_string($accept) && str_contains($accept, ',')) {
+            $accept = array_map('trim', explode(',', $accept));
+        }
+
+        if (! is_array($accept)) {
+            return $next($request);
+        }
+
+        usort($accept, fn ($a, $b): int => str_contains((string) $b, 'application/json') <=> str_contains((string) $a, 'application/json'));
+        $request->headers->set('Accept', implode(', ', $accept));
+
+        return $next($request);
+    }
+}

src/Server/Middleware/ReorderJsonAccept.php

@@ -11,6 +11,8 @@
 use Illuminate\Support\Str;
 use Laravel\Mcp\Server;
 use Laravel\Mcp\Server\Contracts\Transport;
+use Laravel\Mcp\Server\Middleware\AddWwwAuthenticateHeader;
+use Laravel\Mcp\Server\Middleware\ReorderJsonAccept;
 use Laravel\Mcp\Server\Transport\HttpTransport;
 use Laravel\Mcp\Server\Transport\StdioTransport;
 
@@ -19,24 +21,34 @@ class Registrar
     /** @var array<string, callable> */
     protected array $localServers = [];
 
-    /** @var array<string, string> */
-    protected array $registeredWebServers = [];
+    /** @var array<string, Route> */
+    protected array $httpServers = [];
 
     /**
      * @param  class-string<Server>  $serverClass
      */
     public function web(string $route, string $serverClass): Route
     {
-        $this->registeredWebServers[$route] = $serverClass;
+        // https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#listening-for-messages-from-the-server
+        Router::get($route, fn (): \Illuminate\Contracts\Routing\ResponseFactory|\Illuminate\Http\Response => response(status: 405));
 
-        return Router::post($route, fn (): mixed => $this->startServer(
+        $route = Router::post($route, fn (): mixed => $this->startServer(
             $serverClass,
             fn (): HttpTransport => new HttpTransport(
                 $request = request(),
                 // @phpstan-ignore-next-line
                 (string) $request->header('Mcp-Session-Id')
             ),
-        ))->name('mcp-server.'.$route);
+        ))
+            ->name($this->routeName(ltrim($route, '/')))
+            ->middleware([
+                ReorderJsonAccept::class,
+                AddWwwAuthenticateHeader::class,
+            ]);
+
+        $this->httpServers[$route->uri()] = $route;
+
+        return $route;
     }
 
     /**
@@ -52,30 +64,47 @@ public function local(string $handle, string $serverClass): void
         );
     }
 
+    public function routeName(string $path): string
+    {
+        return 'mcp-server.'.Str::kebab(Str::replace('/', '-', $path));
+    }
+
     public function getLocalServer(string $handle): ?callable
     {
         return $this->localServers[$handle] ?? null;
     }
 
-    public function getWebServer(string $handle): ?string
+    public function getWebServer(string $route): ?Route
     {
-        return $this->registeredWebServers[$handle] ?? null;
+        return $this->httpServers[$route] ?? null;
+    }
+
+    /**
+     * @return array<string, callable|Route>
+     */
+    public function servers(): array
+    {
+        return array_merge(
+            $this->localServers,
+            $this->httpServers,
+        );
     }
 
     public function oauthRoutes(string $oauthPrefix = 'oauth'): void
     {
         Router::get('/.well-known/oauth-protected-resource', fn () => response()->json([
-            'resource' => config('app.url'),
+            'resource' => url('/'),
             'authorization_server' => url('/.well-known/oauth-authorization-server'),
-        ]));
+        ]))->name('mcp.oauth.protected-resource');
 
         Router::get('/.well-known/oauth-authorization-server', fn () => response()->json([
-            'issuer' => config('app.url'),
+            'issuer' => url('/'),
             'authorization_endpoint' => url($oauthPrefix.'/authorize'),
             'token_endpoint' => url($oauthPrefix.'/token'),
             'registration_endpoint' => url($oauthPrefix.'/register'),
             'response_types_supported' => ['code'],
             'code_challenge_methods_supported' => ['S256'],
+            'supported_scopes' => ['mcp:use'],
             'grant_types_supported' => ['authorization_code', 'refresh_token'],
         ]));
 
@@ -97,6 +126,7 @@ public function oauthRoutes(string $oauthPrefix = 'oauth'): void
             return response()->json([
                 'client_id' => $client->id,
                 'redirect_uris' => $client->redirect_uris,
+                'scopes' => 'mcp:use',
             ]);
         });
     }

src/Server/Registrar.php

@@ -51,7 +51,9 @@ public function run(): Response|StreamedResponse
             return response()->stream($this->stream, 200, $this->getHeaders());
         }
 
-        $response = response($this->reply, 200, $this->getHeaders());
+        // Must be 202 - https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#sending-messages-to-the-server
+        $statusCode = $this->reply === null || $this->reply === '' || $this->reply === '0' ? 202 : 200;
+        $response = response($this->reply, $statusCode, $this->getHeaders());
 
         assert($response instanceof Response);