# modelcontextprotocol/php-sdk architecture

> Architecture diagram of the GitHub repository modelcontextprotocol/php-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/php-sdk
- Repository: https://github.com/modelcontextprotocol/php-sdk

## Overview

The MCP PHP SDK provides framework-agnostic client and server runtimes. Its central server workflow is to discover or register capabilities, dispatch incoming MCP requests to their handlers, and communicate over a transport; the client connects to an MCP server and exchanges requests and results. Sessions, stateless protocol support, authorization, notifications, and protocol schemas are supporting capabilities. Relationships are limited to those shown in the excerpts or stated in the README; unsampled subsystem links are documented or left unasserted.

Main entry points: [`src/Server.php`](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server.php) (Server entry), [`src/Client.php`](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Client.php) (Client API), [`src/Server/Transport`](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Transport) (STDIO and HTTP), [`src/Capability/Registry.php`](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Capability/Registry.php) (Capability registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server runtime"]
  node_server_entry["Server entry<br/>[Server.php]"]
  node_server_protocol["Server protocol<br/>[Protocol.php]"]
  node_request_handlers["Request handlers"]
  node_sessions["Session management<br/>[SessionManager.php]"]
  node_session[("Session state<br/>[Session.php]")]
  node_subscriptions["Resource subscriptions"]
end

subgraph group_capabilities["Capabilities"]
  node_capability_attrs["Capability attributes<br/>[Schema.php]"]
  node_discovery["Capability discovery"]
  node_registry["Capability registry<br/>[Registry.php]"]
  node_handlers["Capability invocation"]
end

subgraph group_client["Client runtime"]
  node_client_api["Client API<br/>[Client.php]"]
  node_client_protocol["Client protocol<br/>[Protocol.php]"]
  node_client_state["Client state<br/>[ClientState.php]"]
end

subgraph group_protocol["Protocol and state"]
  node_stateless["Stateless protocol"]
  node_wire_codecs["Wire codecs"]
  node_jsonrpc["JSON-RPC messages"]
  node_mcp_schemas["MCP schemas"]
  node_message_factory["Message factory<br/>[MessageFactory.php]"]
end

subgraph group_transport["Transport and security"]
  node_transports["STDIO and HTTP"]
  node_http_security["HTTP authorization"]
end

node_developer(("PHP application"))
node_mcp_server(("MCP server"))

node_developer -->|"builds server"| node_server_entry
node_server_entry -->|"connects"| node_server_protocol
node_server_entry -->|"listens on"| node_transports
node_server_entry -->|"connects when supported"| node_stateless
node_developer -->|"configures discovery"| node_discovery
node_discovery -.->|"loads capabilities"| node_registry
node_developer -->|"registers capabilities"| node_registry
node_capability_attrs -.->|"describes capabilities"| node_registry
node_server_protocol -.->|"dispatches requests"| node_request_handlers
node_request_handlers -->|"resolves capabilities"| node_registry
node_request_handlers -->|"invokes capability"| node_handlers
node_sessions -->|"manages sessions"| node_session
node_session -->|"reads and writes"| node_sessions
node_subscriptions -->|"tracks subscriptions"| node_session
node_transports -.->|"may apply middleware"| node_http_security
node_stateless -.->|"uses protocol revisions"| node_wire_codecs
node_server_protocol -.->|"exchanges messages"| node_jsonrpc
node_jsonrpc -.->|"carries MCP data"| node_mcp_schemas
node_message_factory -->|"creates messages"| node_jsonrpc
node_developer -->|"builds client"| node_client_api
node_client_api -->|"sends requests"| node_client_protocol
node_client_api -.->|"connects through"| node_transports
node_client_protocol -.->|"uses state"| node_client_state
node_client_api -->|"calls tools and reads resources"| node_mcp_server
node_mcp_server -->|"communicates over"| node_transports

click node_server_entry "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server.php"
click node_server_protocol "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Protocol.php"
click node_request_handlers "https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Handler/Request"
click node_sessions "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Session/SessionManager.php"
click node_session "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Session/Session.php"
click node_subscriptions "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Resource/SessionSubscriptionManager.php"
click node_capability_attrs "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Capability/Attribute/Schema.php"
click node_discovery "https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Capability/Discovery"
click node_registry "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Capability/Registry.php"
click node_handlers "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Capability/Registry/ReferenceHandler.php"
click node_client_api "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Client.php"
click node_client_protocol "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Client/Protocol.php"
click node_client_state "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Client/State/ClientState.php"
click node_transports "https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Transport"
click node_http_security "https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Transport/Http/Middleware"
click node_stateless "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Stateless/StatelessProtocol.php"
click node_wire_codecs "https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Wire"
click node_jsonrpc "https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Schema/JsonRpc"
click node_mcp_schemas "https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Schema"
click node_message_factory "https://github.com/modelcontextprotocol/php-sdk/blob/main/src/JsonRpc/MessageFactory.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_server_protocol,node_request_handlers,node_sessions,node_session,node_subscriptions toneBlue
class node_capability_attrs,node_discovery,node_registry,node_handlers toneAmber
class node_client_api,node_client_protocol,node_client_state,node_mcp_server toneMint
class node_stateless,node_wire_codecs,node_jsonrpc,node_mcp_schemas,node_message_factory toneRose
class node_transports,node_http_security,node_developer toneIndigo
```

## Components

### Server runtime

- [Server entry](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server.php): `src/Server.php`
- [Server protocol](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Protocol.php): `src/Server/Protocol.php`
- [Request handlers](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Handler/Request): `src/Server/Handler/Request`
- [Session management](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Session/SessionManager.php): `src/Server/Session/SessionManager.php`
- [Session state](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Session/Session.php): `src/Server/Session/Session.php`
- [Resource subscriptions](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Resource/SessionSubscriptionManager.php): `src/Server/Resource/SessionSubscriptionManager.php`

### Capabilities

- [Capability attributes](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Capability/Attribute/Schema.php): `src/Capability/Attribute/Schema.php`
- [Capability discovery](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Capability/Discovery): `src/Capability/Discovery`
- [Capability registry](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Capability/Registry.php): `src/Capability/Registry.php`
- [Capability invocation](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Capability/Registry/ReferenceHandler.php): `src/Capability/Registry/ReferenceHandler.php`

### Client runtime

- [Client API](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Client.php): `src/Client.php`
- [Client protocol](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Client/Protocol.php): `src/Client/Protocol.php`
- [Client state](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Client/State/ClientState.php): `src/Client/State/ClientState.php`

### Protocol and state

- [Stateless protocol](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/Server/Stateless/StatelessProtocol.php): `src/Server/Stateless/StatelessProtocol.php`
- [Wire codecs](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Wire): `src/Server/Wire`
- [JSON-RPC messages](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Schema/JsonRpc): `src/Schema/JsonRpc`
- [MCP schemas](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Schema): `src/Schema`
- [Message factory](https://github.com/modelcontextprotocol/php-sdk/blob/main/src/JsonRpc/MessageFactory.php): `src/JsonRpc/MessageFactory.php`

### Transport and security

- [STDIO and HTTP](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Transport): `src/Server/Transport`
- [HTTP authorization](https://github.com/modelcontextprotocol/php-sdk/tree/main/src/Server/Transport/Http/Middleware): `src/Server/Transport/Http/Middleware`

### Other components

- **PHP application**
- **MCP server**

## Connections

- PHP application → Server entry: builds server (evidence: `README.md`)
- Server entry → Server protocol: connects (evidence: `src/Server.php`)
- Server entry → STDIO and HTTP: listens on (evidence: `src/Server.php`)
- Server entry → Stateless protocol: connects when supported (evidence: `src/Server.php`)
- PHP application → Capability discovery: configures discovery (evidence: `README.md`)
- Capability discovery → Capability registry: loads capabilities (evidence: `src/Capability/Discovery/HandlerResolver.php`)
- PHP application → Capability registry: registers capabilities (evidence: `README.md`)
- Capability attributes → Capability registry: describes capabilities (evidence: `src/Capability/Registry.php`)
- Server protocol → Request handlers: dispatches requests
- Request handlers → Capability registry: resolves capabilities (evidence: `src/Server/Handler/Request/CallToolHandler.php`)
- Request handlers → Capability invocation: invokes capability (evidence: `src/Server/Handler/Request/CallToolHandler.php`)
- Session management → Session state: manages sessions (evidence: `src/Server/Session/SessionManager.php`)
- Session state → Session management: reads and writes (evidence: `src/Server/Session/Session.php`)
- Resource subscriptions → Session state: tracks subscriptions (evidence: `src/Server/Resource/SessionSubscriptionManager.php`)
- STDIO and HTTP → HTTP authorization: may apply middleware (evidence: `src/Server/Transport/Http/Middleware/ClientRegistrationMiddleware.php`)
- Stateless protocol → Wire codecs: uses protocol revisions
- Server protocol → JSON-RPC messages: exchanges messages
- JSON-RPC messages → MCP schemas: carries MCP data (evidence: `src/Schema/JsonRpc/Error.php`)
- Message factory → JSON-RPC messages: creates messages (evidence: `src/JsonRpc/MessageFactory.php`)
- PHP application → Client API: builds client (evidence: `README.md`)
- Client API → Client protocol: sends requests (evidence: `src/Client.php`)
- Client API → STDIO and HTTP: connects through
- Client protocol → Client state: uses state
- Client API → MCP server: calls tools and reads resources (evidence: `README.md`)
- MCP server → STDIO and HTTP: communicates over (evidence: `README.md`)