[Client] Implement PHP MCP Client Component in php-sdk

[robertoperuzzo]

Is your feature request related to a problem? Please describe

The current PHP SDK focuses exclusively on server-side MCP implementation. However, the Model Context Protocol (MCP) specification defines both server and client sides, and a complete SDK should support both directions of communication. Without a client component, PHP applications cannot programmatically connect to and consume services from MCP servers, limiting the ecosystem's potential for integration and automation.

Currently, PHP developers looking to build MCP clients must either use standalone libraries (like php-mcp/client or swisnl/mcp-client) or implement their own solutions, fragmenting the ecosystem. This issue aims to bring a unified, officially supported client implementation into the modelcontextprotocol/php-sdk repository as a sub-component, following the same development practices and standards as the existing server component.

Describe the solution you'd like

Implement a src/Client sub-component within the php-sdk repository that provides a comprehensive, well-designed PHP client for interacting with MCP servers. The implementation should:

1. Follow the existing SDK architecture and patterns

   • Align with the server component's code structure and conventions
   • Adopt Symfony's coding standards and backward compatibility promise
   • Use attribute-based configuration where appropriate
   • Integrate with the existing transport layer concepts

2. Provide both synchronous and asynchronous APIs

   • Simple, blocking methods for straightforward use cases ($client->listTools(), $client->callTool())
   • Promise-based async methods for advanced scenarios ($client->listToolsAsync())
   • Leverage existing async infrastructure (ReactPHP or consider php-runtime/runtime for transport agnosticism)

3. Support multiple transport mechanisms

   • STDIO transport (for spawning and communicating with server processes)
   • HTTP/SSE transport (for communicating with remote MCP servers)
   • Extensible architecture for custom transports

4. Handle the complete client lifecycle

   • Connection initialization and MCP handshake
   • Capability negotiation
   • Session management
   • Graceful disconnection and cleanup

5. Implement core MCP client operations

   • List and call tools (tools/list, tools/call)
   • List and read resources (resources/list, resources/read, resources/subscribe)
   • List and get prompts (prompts/list, prompts/get)
   • Handle server notifications (e.g., resources/updated, tools/list_changed)
   • Support logging levels and progress notifications

6. Provide robust error handling

   • Specific exception types for different failure scenarios
   • Timeout management
   • Connection recovery strategies

7. Integrate with PSR standards

   • PSR-3 (LoggerInterface) for logging
   • PSR-16 (SimpleCacheInterface) for optional caching
   • PSR-14 (EventDispatcherInterface) for notification handling

Implementation Plan

• Phase 1: Research & Analysis

  • Analyze existing client implementations to identify best practices and patterns
    • php-mcp/client - ReactPHP-based with dual sync/async API
    • swisnl/mcp-client - Promise-based with tool annotations support
  • Review the current modelcontextprotocol/php-sdk architecture to identify:
    • Shared code that could be reused between client and server components
    • Common abstractions (transports, JSON-RPC handling, schema definitions)
    • Session management patterns
    • Event/notification infrastructure
  • Document findings and propose the client architecture that best aligns with existing patterns

• Phase 2: Architecture & Design

  • Design the src/Client namespace structure following the existing src/Server patterns
  • Define client builder API similar to Server::builder()
  • Specify transport abstraction layer (evaluate php-runtime/runtime vs. ReactPHP)
  • Design configuration system (similar to ServerBuilder but for client capabilities)
  • Plan integration points with existing shared code (JsonRpc, Schema, Capability)

• Phase 3: Core Implementation

  • Implement base Client class with builder pattern
  • Implement transport layer
    • STDIO transport (for local server processes)
    • HTTP/SSE transport (for remote servers)
  • Implement connection lifecycle management
    • Initialize and handshake
    • Capability negotiation
    • Session management
    • Graceful disconnection
  • Implement core MCP operations
    • Tools operations (list, call)
    • Resources operations (list, read, subscribe, unsubscribe)
    • Prompts operations (list, get)
  • Implement notification handling system

• Phase 4: API Refinement

  • Implement synchronous API (blocking methods)
  • Implement asynchronous API (Promise-based methods)
  • Add PSR integration (Logger, Cache, EventDispatcher)
  • Implement exception hierarchy for error handling
  • Add timeout and retry mechanisms

• Phase 5: Testing & Documentation

  • Write unit tests for all client components
  • Write integration tests with real MCP servers
  • Create functional tests for transport mechanisms
  • Write comprehensive documentation
    • Client builder reference
    • Transport configuration guide
    • Usage examples (both sync and async)
    • Integration guides (similar to server docs)
  • Create example applications demonstrating client usage

• Phase 6: Refinement & Stabilization

  • Gather feedback from early adopters
  • Optimize performance and resource usage
  • Ensure backward compatibility with the existing server component
  • Consider package split strategy for future releases (if needed)
  • Update README and main documentation to reflect client availability

Describe alternatives you've considered

1. Maintain separate client libraries

   • Keep php-mcp/client and swisnl/mcp-client as standalone packages
   • Pros: No disruption to existing projects, maintains current maintenance structures
   • Cons: Fragments the PHP MCP ecosystem, inconsistent APIs, duplicated effort, lack of unified standards

2. Recommend one existing library as "official"

   • Endorse one of the existing client libraries without bringing it into php-sdk
   • Pros: Quick solution, no implementation work needed
   • Cons: Doesn't align with the goal of a unified SDK, may not meet all architectural requirements

3. Client as a separate Composer package

   • Create mcp/client as a sibling package to mcp/sdk
   • Pros: Clearer separation of concerns, independent versioning
   • Cons: May lead to code duplication with server component, harder to maintain shared abstractions initially

4. Adopt php-runtime/runtime for transport agnosticism

   • Use php-runtime/runtime instead of directly depending on ReactPHP
   • Pros: More flexible, allows users to choose their async runtime (ReactPHP, Amp, Swoole, etc.)
   • Cons: Adds another abstraction layer, may complicate initial implementation

Additional context

• This proposal aligns with the SDK roadmap item: "Implement Client component"
• The work should build upon insights from php-mcp/client, which was initially developed by Kyrian Obikwelu (who also contributed to the server component)
• Chris (chr-hertel) suggested implementing this as a sub-component in src/Client, with potential package splitting in future releases
• The client should share common code with the server component where possible (JSON-RPC handling, schema definitions, capability models)
• Consider transport agnosticism using php-runtime/runtime to avoid tight coupling to ReactPHP
• The implementation should maintain the experimental status until stabilization, following Symfony's experimental component guidelines

Related Issues & References

• Closes [Client] (Re-)Implement Client component #15 (original client implementation request)
• Related to MCP Specification - Client
• Reference implementations: TypeScript SDK, Python SDK

---

Note for Contributors: If you're interested in working on any phase of this implementation, please comment below to coordinate efforts and avoid duplicate work. Let's discuss the architectural decisions together to ensure the client component integrates seamlessly with the existing SDK.

[stuartbrameld]

this is fantastic

Analyze existing client implementations to identify best practices and patterns

• php-mcp/client - ReactPHP-based with dual sync/async API
• swisnl/mcp-client - Promise-based with tool annotations support

may also be worth looking at https://github.com/prism-php/relay

[chr-hertel]

Hey @robertoperuzzo, thanks for the write up and jumping on this - looking forward to this!

Some thoughts I had while reading:

• PSR for HTTP might be worth adopting here
• I really want to stretch your point with examples: they are fundamental to me 👍
• It might be also helpful to look at @camilleislasse PR at symfony/ai for bringing in a MCP Client to the Agent component: [Agent] Enable remote MCP tools for agents symfony/ai#1129
• we can split mcp/sdk in mcp/client and mcp/server later based on this very repository 👍
• We should aim for going incremental, for example the first iteration doesn't have to support all transports or MCP operations, but create the foundation for it

so what could be the first step?
bringing in a simple STDIO-based client that can connect, list and call tools of one server?
or what comes to your mind?

cc @CodeWithKyrian feel free to share your thoughts and insights please :)

[CodeWithKyrian]

Thanks for the detailed proposal @robertoperuzzo . This is a really solid write-up and I agree with the direction overral 👍🏽

First, on where this should live:
I agree that starting with a src/Client subcomponent makes the most sense now. It doesn't disturb anything, lets us share abstractions cleanly and the door's still open for splitting if need be.

On the sync vs async API discussion, this is probably the biggest point I want to stretch abit.

The dual sync/async API idea came up probably becaue of my earlier php-mcp/client, which was ReactPHP-based. That design made sense at the time because both the client and server implementations were built directly on ReactPHP. But it also created a had dependency on an event loop, which is something we'd really like to avoid at the SDK level going forward.

One of the thing I'm happiest about in the current server SDK is that we removed the hard dependency on any async runtime and made it transport-driven instead. Whether it's actually blocking or async is entirely an implementation detail of the transport. So I think the client should follow that same philosophy - let transports decide.

We can either then have first party transports in the SDK for common runtimes (for both Client and Server), or provide enough guide so the community can build transports for their specific runtimes.

Relating to php-runtime/runtime:
I like the idea in theory, but I don't have enough real world usage with so I can't really say much there. But I believe transport agnoticism is the goal, unless it can't be achieved 🤷🏽

And finally I agree with @chr-hertel that we should go incremental and start with STDIO transport. That was the same pathway we went with the server and kept moving things around after the HTTP was introduced till it fit!

[jormeijer]

@CodeWithKyrian, +1 on the transport-driven approach.

I’ve been scratching my head about how to abstract async operations at the SDK level (promises/fibers/loops), but in practice it gets ugly fast and ends up leaking runtime details everywhere. Keeping the Client transport-agnostic feels like the right move.

That also makes it easy to offer runtime-specific first-party/community transports without forcing a global choice. E.g. a ReactSseTransport (or ReactStreamableHttpTransport) can do the heavy lifting with the right React HTTP client + loop integration, while a Swoole/OpenSwoole transport can use coroutine HTTP and look synchronous from the client’s perspective.

Re: symfony/runtime (php-runtime/runtime): I don’t have real-world experience with it either, but my understanding is it’s mainly a bootstrap/entrypoint abstraction for hosting an app under different runtimes, not an async/IO abstraction itself.

[robertoperuzzo]

Thank you very much for your feedback, which is essential to getting me in and understanding all the aspects involved.

Summarising what you said, the starting key points are:

1. Start with a src/Client subcomponent
2. Go incremental, bringing in a simple STDIO-based client that can connect, list and call tools
3. blocking/async API is a transport matter, and we want to avoid hard dependency on an event loop (like ReactPHP)

The first step could be (as @chr-hertel and @CodeWithKyrian said) implementing a Client with only the STDIO transporter.

[chr-hertel]

I know a guy quite experienced with the runtime thingy - looking at you @Nyholm 😆 what do you think?

[jormeijer]

One concrete API direction I’d like to suggest is around the async surface.

I propose exposing both:

    $client->sendRequest(Request $request): Response
    $client->sendRequestAsync(Request $request): Promise

with the async variant being the “primary” API and returning a Promise (for example via php-http/promise), allowing fluent usage like:

    $client->sendRequestAsync($request)
        ->then(fn (Response $response) => ...);

The alternative would be a callback-based API like:

    $client->sendRequestAsync(Request $request, Closure $callback): void

The MCP protocol itself is asynchronous by design, so async requests as the default is a must. The synchronous sendRequest() would then simply be a blocking, convenience wrapper. A simplified variant that aligns with what most PHP developers are used to.

Using Promises here gives us a clean, composable abstraction with structured error handling. Also, in practice I’ve found callback-style APIs harder to compose and reason about, especially in long-running runtimes. User callbacks can accidentally become a lifecycle/memory hazard. Closures often capture $this or other objects (containers, loggers). If a request stalls, reconnect loops, or a stream stays open longer than expected, those captured references can stay retained for the lifetime of the process.

Curious how others feel about returning a Promise here versus callbacks, and whether a dependency on php-http/promise feels acceptable given we already depend on php-http/discovery.

Edit
But, that will also mean that the host app needs to provide a Promises/A+ compatible promise library (likeguzzle/promises)