Skip to content

events.md

Latest commit

 

History

History
107 lines (73 loc) · 4.23 KB

events.md

File metadata and controls

107 lines (73 loc) · 4.23 KB
Raw

Events

The MCP SDK provides a PSR-14 compatible event system that allows you to hook into the server's lifecycle. Events enable request/response modification, and other user-defined behaviors.

Setup

Configure an event dispatcher when building your server:

use Mcp\Event\RequestEvent;
use Mcp\Server;
use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();

// Register your listeners
$dispatcher->addListener(RequestEvent::class, function (RequestEvent $event) {
    // Handle any incoming request
    if ($event->getMethod() === 'tools/call') {
        // Handle tool call requests specifically
    }
});

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

Protocol Events

The SDK dispatches 4 broad event types at the protocol level, allowing you to observe and modify all server operations:

RequestEvent

Dispatched: When any request is received from the client, before it's processed by handlers.

Properties:

  • getRequest(): Request - The incoming request
  • setRequest(Request $request): void - Modify the request before processing
  • getSession(): SessionInterface - The current session
  • getMethod(): string - Convenience method to get the request method

ResponseEvent

Dispatched: When a successful response is ready to be sent to the client, after handler execution.

Properties:

  • getResponse(): Response - The response being sent
  • setResponse(Response $response): void - Modify the response before sending
  • getRequest(): Request - The original request
  • getSession(): SessionInterface - The current session
  • getMethod(): string - Convenience method to get the request method

ErrorEvent

Dispatched: When an error occurs during request processing.

Properties:

  • getError(): Error - The error being sent
  • setError(Error $error): void - Modify the error before sending
  • getRequest(): Request - The original request. Messages that fail to parse are rejected before this event, so a listener never sees them.
  • getThrowable(): ?\Throwable - The exception that caused the error (if any)
  • getSession(): SessionInterface - The current session

NotificationEvent

Dispatched: When a notification is received from the client, before it's processed by handlers.

Properties:

  • getNotification(): Notification - The incoming notification
  • setNotification(Notification $notification): void - Modify the notification before processing
  • getSession(): SessionInterface - The current session
  • getMethod(): string - Convenience method to get the notification method

Protocol 2026-07-28

Requests on protocol version 2026-07-28 dispatch the same request, response and error events, with a few differences:

  • ResponseEvent fires on every InputRequiredResult round, not only on the final result. Listeners that only care about completed calls need to check the result type.
  • getSession() returns a new in-memory session for each request. Anything a listener stores there is gone by the next request.
  • NotificationEvent is not dispatched, since this protocol version runs no notification handlers.
  • server/discover and subscriptions/listen dispatch no events.

List Change Events

These events are dispatched when the lists of available capabilities change:

Event Description
ToolListChangedEvent Dispatched when the list of available tools changes
ResourceListChangedEvent Dispatched when the list of available resources changes
ResourceTemplateListChangedEvent Dispatched when the list of available resource templates changes
PromptListChangedEvent Dispatched when the list of available prompts changes

These events carry no data and are used to notify clients that they should refresh their capability lists.

use Mcp\Event\ToolListChangedEvent;

$dispatcher->addListener(ToolListChangedEvent::class, function (ToolListChangedEvent $event) {
    $logger->info('Tool list has changed, clients should refresh');
});