Server builder

The server Builder is a fluent builder class that simplifies the creation and configuration of an MCP server instance. It provides methods for setting server information, configuring discovery, registering capabilities, and customizing various aspects of the server behavior.

Basic Usage

There are two ways to obtain a server builder instance:

Method 1: Static Builder Method (Recommended)

use Mcp\Server;

$server = Server::builder()
    ->setServerInfo('My MCP Server', '1.0.0')
    ->setDiscovery(__DIR__, ['.'], excludeDirs: ['vendor'])
    ->build();

Method 2: Direct Instantiation

use Mcp\Server\Builder;

$server = (new Builder())
    ->setServerInfo('My MCP Server', '1.0.0')
    ->setDiscovery(__DIR__, ['.'], excludeDirs: ['vendor'])
    ->build();

Both methods return a Builder instance that you can configure with fluent methods. The build() method returns the final Server instance ready for use.

Server Configuration

Server Information

Set the server's identity with name, version, and optional description:

use Mcp\Schema\Icon;
use Mcp\Server;

$server = Server::builder()
    ->setServerInfo(
        name: 'Calculator Server',
        version: '1.2.0',
        description: 'Advanced mathematical calculations',
        icons: [new Icon('https://example.com/icon.png', 'image/png', ['64x64'])],
        websiteUrl: 'https://example.com',
    );

Parameters:

$name (string): The server name
$version (string): Version string (semantic versioning recommended)
$description (string|null): Optional description
$icons (Icon[]|null): Optional array of server icons
$websiteUrl (string|null): Optional server website URL
$title (string|null): Optional human-readable display title, distinct from $name

Pagination Limit

Configure the maximum number of items returned in paginated responses:

$server = Server::builder()
    ->setPaginationLimit(100); // Default: 50

Instructions

Provide hints to help AI models understand how to use your server:

$server = Server::builder()
    ->setInstructions('This calculator supports basic arithmetic operations. Use the calculate tool for math operations and check the config resource for current settings.');

Protocol Version

By default the server negotiates the protocol revision with each client during the initialize handshake, and you do not need to configure anything. setProtocolVersion() pins that handshake to exactly one revision instead:

use Mcp\Schema\Enum\ProtocolVersion;

$server = Server::builder()
    ->setProtocolVersion(ProtocolVersion::V2025_06_18);

See Protocol versions for how negotiation resolves and what pinning changes. It only pins the handshake era; to narrow or remove what the modern leg answers for, use setModernVersions() / withoutModernEra() — see Serving both eras.

Modern-Era Options

build() returns a server that answers both protocol eras, and none of the following is required to serve either one. Each knob is covered in depth elsewhere: Asking for input for the first two, Caching, Subscriptions, and Serving both eras for the last.

use Mcp\Schema\Enum\CacheScope;
use Mcp\Schema\Enum\ProtocolVersion;
use Mcp\Server\Subscription\Psr16NotificationBus;
use Mcp\Server\Wire\CachePolicy;

$server = Server::builder()
    // Signs the state a multi round-trip request carries through the client.
    // The same key must reach every process that might serve the retry.
    ->setRequestState($_ENV['MCP_REQUEST_STATE_KEY'], ttl: 600)

    // Bounds the input-required shim, which fulfils an `InputRequiredResult`
    // over a handshake-era connection. `withoutInputRequiredShim()` turns it off.
    ->setInputRequiredLimits(maxRounds: 4, roundTimeout: 120)

    // Caching hints stamped on cacheable results. Defaults to `ttlMs: 0, private`.
    ->setCachePolicy(CachePolicy::default(30_000)->withMethod('tools/list', 3_600_000, CacheScope::Public))

    // Delivery for `subscriptions/listen`, and how long such a stream is held.
    ->setNotificationBus(new Psr16NotificationBus($cache))
    ->setSubscriptionLifetime(0)

    // Narrow the modern leg, or drop it entirely.
    ->setModernVersions([ProtocolVersion::V2026_07_28])
    ->build();

buildStateless() returns the modern dispatcher alone, for an endpoint that serves no handshake-era traffic at all. Its requests are checked against the SEP-2243 standard headers — that Mcp-Method, Mcp-Name and Mcp-Param-* agree with the body they travel with. setHeaderValidator(false) turns that check off, which is needed only when the dispatcher is served by a transport that has no header layer to check.

Discovery Configuration

Required when using MCP attributes. If you're using PHP attributes (#[McpTool], #[McpResource], #[McpResourceTemplate], #[McpPrompt]) to define your MCP elements, you MUST configure discovery to tell the server where to look for these attributes.

$server = Server::builder()
    ->setDiscovery(
        basePath: __DIR__,
        scanDirs: ['.', 'src', 'lib'],           // Where to look for MCP attributes
        excludeDirs: ['vendor', 'tests'],        // Where NOT to look
        cache: $cacheInstance,                   // Optional: cache discovered elements
        namePatterns: ['*.php', '*.inc'],        // Optional: list of filename patterns to match
    );

Parameters:

$basePath (string): Base directory for discovery (typically __DIR__)
$scanDirs (array): Directories to recursively scan for #[McpTool], #[McpResource], etc. All subdirectories are included. (default: ['.', 'src'])
$excludeDirs (array): Directory names to exclude within the scanned directories during recursive scanning
$cache (CacheInterface|null): Optional PSR-16 cache to store discovered elements for performance
$namePatterns (array): Optional list of patterns (regexp, glob, or string) for file names (default: ['*.php'])

Basic Discovery (scans current directory and src/):

$server = Server::builder()
    ->setDiscovery(__DIR__, excludeDirs: ['vendor'])  // Scans '.' and 'src'
    ->build();

!!! warning Always exclude vendor/ when the scanned directories contain it. The recursive scan tries to load every class it finds, and a single file that cannot be loaded makes the scan abort — the server then reports an empty element list instead of an error.

Production Setup with Caching:

use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

// Cache discovered elements to avoid filesystem scanning on every server start
$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery'));

$server = Server::builder()
    ->setDiscovery(
        basePath: __DIR__,
        scanDirs: ['src', 'lib'],                    // Scan these directories recursively
        excludeDirs: ['vendor', 'tests', 'temp'],    // Skip these directory names within scanned dirs
        cache: $cache                                // Cache for performance
    )
    ->build();

How excludeDirs works:

If scanning src/ and there's src/vendor/, it will be excluded
If scanning lib/ and there's lib/tests/, it will be excluded
But if vendor/ and tests/ are at the same level as src/, they're not scanned anyway (not in scanDirs)

Performance: Always use a cache in production. The first run scans and caches all discovered MCP elements, making subsequent server startups nearly instantaneous.

Service Dependencies

Container

The container is used to resolve handlers and their dependencies when handlers inject dependencies in their constructors. The SDK includes a basic container with simple auto-wiring capabilities.

use Mcp\Capability\Registry\Container;

// Use the default basic container
$container = new Container();
$container->set(DatabaseService::class, new DatabaseService($pdo));
$container->set(\PDO::class, $pdo);

$server = Server::builder()
    ->setContainer($container)
    ->build();

Basic Container Features:

Supports constructor auto-wiring for classes with parameterless constructors
Resolves dependencies where all parameters are type-hinted classes/interfaces known to the container
Supports parameters with default values
Does NOT support scalar/built-in type injection without defaults
Detects circular dependencies

You can also use any PSR-11 compatible container (Symfony DI, PHP-DI, Laravel Container, etc.).

Logger

Provide a PSR-3 logger instance for internal server logging (request/response processing, errors, session management, transport events):

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('mcp-server');
$logger->pushHandler(new StreamHandler('mcp.log', Logger::INFO));

$server = Server::builder()
    ->setLogger($logger);

Event Dispatcher

Configure event dispatching:

$server = Server::builder()
    ->setEventDispatcher($eventDispatcher);

Complete Example

Here's a comprehensive example showing all major configuration options:

use Mcp\Server;
use Mcp\Server\Session\FileSessionStore;
use Mcp\Capability\Registry\Container;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Setup dependencies
$logger = new Logger('mcp-server');
$logger->pushHandler(new StreamHandler('mcp.log', Logger::INFO));

$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery'));
$sessionStore = new FileSessionStore(__DIR__ . '/sessions');

// Setup container with dependencies
$container = new Container();
$container->set(\PDO::class, new \PDO('sqlite::memory:'));
$container->set(DatabaseService::class, new DatabaseService($container->get(\PDO::class)));

// Build server
$server = Server::builder()
    // Server identity
    ->setServerInfo('Advanced Calculator', '2.1.0')

    // Performance and behavior
    ->setPaginationLimit(100)
    ->setInstructions('Use calculate tool for math operations. Check config resource for current settings.')

    // Discovery with caching
    ->setDiscovery(__DIR__, ['src'], ['vendor', 'tests'], $cache)

    // Session management
    ->setSession($sessionStore)

    // Services
    ->setLogger($logger)
    ->setContainer($container)

    // Manual capability registration
    ->addTool([Calculator::class, 'advancedCalculation'], 'advanced_calc')
    ->addResource([Config::class, 'getSettings'], 'config://app/settings', 'app_settings')

    // Build the server
    ->build();

Method Reference

Method	Parameters	Description
`setServerInfo()`	name, version, description?	Set server identity
`setPaginationLimit()`	limit	Set max items per page
`setInstructions()`	instructions	Set usage instructions
`setProtocolVersion()`	protocolVersion	Pin the handshake to one protocol revision
`setModernVersions()`	versions	Narrow the revisions the modern (2026-07-28) leg answers for
`withoutModernEra()`	-	Serve the handshake era only
`setRequestState()`	key, ttl?	Signing key and lifetime for multi round-trip request state
`setInputRequiredLimits()`	maxRounds, roundTimeout	Bound the input-required shim on handshake-era connections
`withoutInputRequiredShim()`	-	Do not fulfil an `InputRequiredResult` over a handshake-era connection
`setCachePolicy()`	policy	Set the `ttlMs`/`cacheScope` hints on cacheable results
`setNotificationBus()`	bus	Delivery for `subscriptions/listen` streams
`setSubscriptionLifetime()`	seconds	How long a subscription stream is held open (`0` = unbounded)
`setHeaderValidator()`	enabled	Toggle the SEP-2243 standard-header check on `buildStateless()`
`setDiscovery()`	basePath, scanDirs?, excludeDirs?, cache?	Configure attribute discovery
`setSession()`	sessionStore?, sessionManager?, gcProbability?, gcDivisor?	Configure session management
`setLogger()`	logger	Set PSR-3 logger
`setContainer()`	container	Set PSR-11 container
`setEventDispatcher()`	dispatcher	Set PSR-14 event dispatcher
`addRequestHandler()`	handler	Prepend a single custom request handler
`addRequestHandlers()`	handlers	Prepend multiple custom request handlers
`addNotificationHandler()`	handler	Prepend a single custom notification handler
`addNotificationHandlers()`	handlers	Prepend multiple custom notification handlers
`addTool()`	handler, name?, title?, description?, annotations?, inputSchema?, ...	Register tool
`addResource()`	handler, uri, name?, title?, description?, mimeType?, size?, annotations?, icons?, meta?	Register resource
`addResourceTemplate()`	handler, uriTemplate, name?, title?, description?, mimeType?, annotations?, meta?	Register resource template
`addPrompt()`	handler, name?, title?, description?, icons?, meta?	Register prompt
`add()`	definition, handler	Register an element from a schema VO + handler pair
`build()`	-	Create the server instance
`buildStateless()`	supportedVersions?	Create the modern dispatcher alone, for `StatelessHttpTransport`

Navigation Menu

Uh oh!

Server builder

Basic Usage

Method 1: Static Builder Method (Recommended)

Method 2: Direct Instantiation

Server Configuration

Server Information

Pagination Limit

Instructions

Protocol Version

Modern-Era Options

Discovery Configuration

Service Dependencies

Container

Logger

Event Dispatcher

Complete Example

Method Reference

Uh oh!

FilesExpand file tree

server-builder.md

Latest commit

History

server-builder.md

File metadata and controls

Server builder

Basic Usage

Method 1: Static Builder Method (Recommended)

Method 2: Direct Instantiation

Server Configuration

Server Information

Pagination Limit

Instructions

Protocol Version

Modern-Era Options

Discovery Configuration

Service Dependencies

Container

Logger

Event Dispatcher

Complete Example

Method Reference