MCP Server Authentication Guide for PHP

July 4, 2026 · View on GitHub

This guide explains how to set up a Model Context Protocol (MCP) server with OAuth 2.1 authentication in a standard web hosting environment, such as cPanel.

Overview

The MCP SDK for PHP supports OAuth 2.1 authentication, allowing you to protect your MCP server endpoints and control access to resources. This example demonstrates how to configure and deploy an authenticated MCP server in a standard web hosting environment.

Installation Steps

1. Install the MCP SDK

First, install the MCP SDK using Composer:

composer require logiscape/mcp-sdk-php

This will create a vendor directory containing all necessary dependencies.

2. Upload Files

Upload the following files to your web document root (typically public_html):

/public_html/
├── vendor/                 # Upload entire directory from Composer
├── generate-token.php      # Test token generator (for testing only)
├── mcp-config.php         # Configuration file
├── server_auth.php        # The actual MCP server
└── .htaccess             # Apache configuration (create or modify)

3. Configure Your Server

Edit mcp-config.php with your specific values. The file defaults to RS256 (JWKS-based validation); switch to HS256 for local testing with generate-token.php:

// Set configuration constants
define('MCP_JWT_ALGORITHM', 'HS256');
define('MCP_JWT_SECRET', 'test-secret-key-change-in-production');
define('MCP_AUTH_ISSUER', 'https://example_auth_server.com/');
define('MCP_RESOURCE_ID', 'https://yoursite.com/server_auth.php');

Important Configuration Notes:

MCP_JWT_ALGORITHM: HS256 can be used with generate-token.php while RS256 (the file's default) is recommended for production.
MCP_JWT_SECRET: Replace with a strong, random secret key. Use at least 32 characters.
MCP_AUTH_ISSUER: URL of your OAuth authorization server
MCP_RESOURCE_ID: Full URL to your MCP server endpoint (server_auth.php)

4. Configure Apache (.htaccess)

Add the following rules to your .htaccess file in the document root:

# 1. Pass Authorization header to PHP (REQUIRED for MCP)
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

# 2. Route .well-known endpoint to your MCP server
RewriteRule ^\.well-known/oauth-protected-resource(/.*)?$ /server_auth.php [L]

Why This Is Necessary:

Many shared hosting environments strip the Authorization header by default
The first rule ensures OAuth bearer tokens reach your PHP scripts
The second rule enables OAuth discovery via the well-known endpoint

5. Create Session Directory

Create a directory for storing sessions and protect it:

Create directory: mcp_sessions/
Set permissions to 755
Create mcp_sessions/.htaccess with:
```
Deny from all
```

Testing Your Setup

Development Testing

The included generate-token.php file provides a simple interface for generating test JWT tokens during development:

Access https://yoursite.com/generate-token.php
Generate a token with appropriate claims
Use the token to test your MCP server

⚠️ Security Warning: This token generator is for testing only. Never use it in production.

Verify OAuth Compliance

Your authenticated MCP server will:

Reject unauthenticated requests with HTTP 401
Return metadata at /.well-known/oauth-protected-resource
Accept valid tokens in the Authorization: Bearer <token> header
Create sessions for authenticated clients

Test the authentication flow:

The included file test-client.html features a basic MCP server test tool covering both protocol eras. Without a Bearer Token you should be able to fetch the resource metadata, but any MCP request should fail with a 401 error. With a valid Bearer Token:

Modern era (2026-07-28): "Discover" and "Tools List" send stateless, self-contained requests — protocol metadata travels in each request's _meta (mirrored by the MCP-Protocol-Version header, plus the Mcp-Method request-metadata header), with no handshake and no session.
Legacy era (2025-11-25 and older): "Initialize" performs the classic handshake and captures the returned Mcp-Session-Id, after which the legacy "Tools List" runs against that session.

// Generate a secure key (run once, save the output)
echo bin2hex(random_bytes(32));

Troubleshooting

Common Issues

Authorization header not reaching PHP:

Verify .htaccess rules are applied
Check with your hosting provider for restrictions
Some hosts require different RewriteRule syntax

404 errors on well-known endpoint:

Ensure .htaccess routing is working and points to your actual MCP server file
Verify mod_rewrite is enabled

Token validation failures:

Confirm token audience matches MCP_RESOURCE_ID
Check token expiration
Verify JWT secret matches between issuer and server

Hosting Provider Notes

This configuration works on standard cPanel setups. However, some providers may:

Disable .htaccess modifications
Use custom Apache configurations
Require support tickets for Authorization header access

Contact your hosting provider if the standard configuration doesn't work.

How It Works

Client Request: MCP client sends request without authentication
401 Response: Server returns 401 with WWW-Authenticate header
Discovery: Client fetches /.well-known/oauth-protected-resource
Authorization: Client obtains token from authorization server
Authenticated Request: Client includes Authorization: Bearer <token>
Token Validation: Server validates token and processes request
Session Creation: Server creates session for subsequent requests

Example MCP Server

The included server_auth.php demonstrates:

OAuth token validation via McpServer::withAuth()
Session management for legacy-era clients (2026-07-28 clients are served statelessly)
Protected MCP tools, prompts, and resources registered through the fluent McpServer API
Proper error responses

Register your own tools, prompts, and resources on the McpServer instance to implement your specific MCP functionality while maintaining the authentication framework.