MCP Resources Server Demo

A Laravel (laravel/mcp) demo of an MCP server that exposes exactly one resource — api-docs.json — behind three independent security controls:

1. mTLS — a local Caddy reverse proxy requires and verifies a client certificate before any request reaches Laravel.

2. OAuth 2.1 + PKCE — Laravel Passport (embedded Authorization Server) issues access tokens via the Authorization Code grant with mandatory PKCE (S256), using laravel/mcp's built-in OAuth discovery and dynamic client registration.

3. Granular scope control — the resource only appears in resources/list (and only serves content in resources/read) for tokens carrying the mcp:read-api-docs scope. A token without it sees an empty resource list — it can't discover the resource exists, let alone read it.

This is a precursor demo for a larger MCP Resources Server project — see docs/MCP_DEMO.md for the full architecture writeup.

Setup

composer install
npm install && npm run build
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan passport:keys
php artisan db:seed

php artisan db:seed creates the demo user used to complete the OAuth consent step: test@example.com / password.

Replace storage/app/private/api-docs.json with the real file you want the resource to serve, if you haven't already.

Related MCP server: identity-aware-mcp-server

Testing the demo

You need three terminals.

Terminal 1 — Laravel:

php artisan serve --port=8000

Terminal 2 — Caddy (mTLS-terminating proxy, localhost:8443 → 127.0.0.1:8000):

cd deploy/mtls
./bin/caddy.exe run --config Caddyfile --adapter caddyfile

Terminal 3 — run the scripted end-to-end client:

php deploy/mtls/demo-client.php

This plays the role of a real MCP client: registers itself via POST /oauth/register, generates a PKCE code_verifier/code_challenge, logs in as the seeded demo user, submits the consent screen, exchanges the code for a token, then calls the MCP endpoint over the mTLS connection with resources/list and resources/read. You should see api-docs.json (and only that) listed, with its contents returned.

Run it again with the flag below to request only the base mcp:use scope (no mcp:read-api-docs) and watch the resource disappear from the list — proof the scope gate hides it rather than just rejecting reads:

php deploy/mtls/demo-client.php --no-scope

For negative tests (no client cert, no bearer token) and a manual browser-based walkthrough of the consent screen, see docs/MCP_DEMO.md.

Key files

Status

This is demo-grade, not production-grade: self-signed local certs, Passport running as an embedded Authorization Server (a real deployment would more likely delegate to a standalone IdP), and no automated PHPUnit coverage for the new mTLS/OAuth/scope wiring — it's been verified by actually running the flow, not by a test suite. See the "Notes for the real project" section of docs/MCP_DEMO.md for what carries over.

Built on the Laravel framework, licensed MIT.

MCP-Demo