Skip to content

04-discovery-manual-registration-and-caching.md

Latest commit

 

History

History
193 lines (160 loc) · 6.38 KB

04-discovery-manual-registration-and-caching.md

File metadata and controls

193 lines (160 loc) · 6.38 KB
layout default
title Chapter 4: Discovery, Manual Registration, and Caching
nav_order 4
parent MCP PHP SDK Tutorial

Chapter 4: Discovery, Manual Registration, and Caching

Welcome to Chapter 4: Discovery, Manual Registration, and Caching. In this part of MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

This chapter compares registration strategies and startup optimization patterns.

Learning Goals

  • choose between attribute discovery and explicit registration
  • apply hybrid registration models where needed
  • use discovery caching to reduce startup overhead
  • keep capability inventories deterministic across environments

Strategy Matrix

Strategy Best Fit
discovery-only fast onboarding and convention-driven projects
manual-only strict control and explicit governance requirements
hybrid mixed legacy/new codebases with phased migration

Caching Guidance

  • use PSR-16 caching for discovery metadata in larger codebases.
  • invalidate cache on deployment/version changes.
  • monitor cache misses during cold starts to detect configuration regressions.

Source References

Summary

You now have a registration strategy framework that balances speed and control.

Next: Chapter 5: Transports: STDIO and Streamable HTTP

Source Code Walkthrough

examples/server/oauth-keycloak/keycloak/mcp-realm.json

The mcp-realm module in examples/server/oauth-keycloak/keycloak/mcp-realm.json handles a key part of this chapter's functionality:

{
  "realm": "mcp",
  "enabled": true,
  "registrationAllowed": false,
  "loginWithEmailAllowed": true,
  "duplicateEmailsAllowed": false,
  "resetPasswordAllowed": true,
  "editUsernameAllowed": false,
  "bruteForceProtected": true,
  "accessTokenLifespan": 300,
  "ssoSessionIdleTimeout": 1800,
  "ssoSessionMaxLifespan": 36000,
  "clients": [
    {
      "clientId": "mcp-client",
      "name": "MCP Client Application",
      "description": "Public client for MCP client applications",
      "enabled": true,
      "publicClient": true,
      "standardFlowEnabled": true,
      "directAccessGrantsEnabled": true,
      "serviceAccountsEnabled": false,
      "authorizationServicesEnabled": false,
      "fullScopeAllowed": true,
      "redirectUris": [
        "http://localhost:*",
        "http://127.0.0.1:*"
      ],
      "webOrigins": [
        "http://localhost:*",
        "http://127.0.0.1:*"
      ],
      "defaultClientScopes": [
        "openid",
        "profile",

This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.

examples/server/oauth-microsoft/docker-compose.yml

The docker-compose module in examples/server/oauth-microsoft/docker-compose.yml handles a key part of this chapter's functionality:

services:
  php:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: mcp-php-microsoft
    volumes:
      - ../../../:/app
    working_dir: /app
    env_file:
      - .env
    environment:
      AZURE_TENANT_ID: ${AZURE_TENANT_ID:-}
      AZURE_CLIENT_ID: ${AZURE_CLIENT_ID:-}
      AZURE_CLIENT_SECRET: ${AZURE_CLIENT_SECRET:-}
    command: >
      sh -c "mkdir -p /app/examples/server/oauth-microsoft/sessions;
      chmod -R 0777 /app/examples/server/oauth-microsoft/sessions;
      touch /app/examples/server/oauth-microsoft/dev.log;
      chmod 0666 /app/examples/server/oauth-microsoft/dev.log;
      touch /app/examples/server/dev.log;
      chmod 0666 /app/examples/server/dev.log;
      composer install --no-interaction --quiet 2>/dev/null || true;
      php-fpm"
    networks:
      - mcp-network

  nginx:
    image: nginx:alpine
    container_name: mcp-nginx-microsoft
    ports:
      - "${MCP_HTTP_PORT:-8000}:80"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ../../../:/app:ro

This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.

composer.json

The composer module in composer.json handles a key part of this chapter's functionality:

{
  "name": "mcp/sdk",
  "description": "Model Context Protocol SDK for Client and Server applications in PHP",
  "license": "Apache-2.0",
  "type": "library",
  "authors": [
    {
      "name": "Christopher Hertel",
      "email": "mail@christopher-hertel.de"
    },
    {
      "name": "Kyrian Obikwelu",
      "email": "koshnawaza@gmail.com"
    },
    {
      "name": "Tobias Nyholm",
      "email": "tobias.nyholm@gmail.com"
    }
  ],
  "require": {
    "php": "^8.1",
    "ext-fileinfo": "*",
    "opis/json-schema": "^2.4",
    "php-http/discovery": "^1.20",
    "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
    "psr/clock": "^1.0",
    "psr/container": "^1.0 || ^2.0",
    "psr/event-dispatcher": "^1.0",
    "psr/http-client": "^1.0",
    "psr/http-factory": "^1.1",
    "psr/http-message": "^1.1 || ^2.0",
    "psr/http-server-handler": "^1.0",
    "psr/http-server-middleware": "^1.0",
    "psr/log": "^1.0 || ^2.0 || ^3.0",
    "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",

This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.

How These Components Connect

flowchart TD
    A[mcp-realm]
    B[docker-compose]
    C[composer]
    A --> B
    B --> C
Loading