Skip to content

Conversation

@soyuka
Copy link
Member

@soyuka soyuka commented Oct 15, 2025

Q A
Branch? main
License MIT

Bringing MCP capabilities to API Platform !

This is huge as for every supported operation you will be able to activate MCP support by only setting mcp: true on your resource/operation.

TODO:

  • review this draft
  • add a mcp flag to operation/resource to be able to select which operations to expose (default will be none)
  • missing completion (probably do this in another PR)
  • annotations support
  • decide for formats and check if json-ld is not available how things work
  • test a tool when there's an URI variable
  • [Server] Handler context modelcontextprotocol/php-sdk#108 actually we had to create new RequestHandler and could not use the ones from the SDK because of this issue, I'm wondering if we could make something better

Because of the last issue, we're not using the default handler mechanics and we don't need the following compiler pass:

final class McpPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        if (!$container->hasDefinition('api_platform.mcp.server.builder')) {
            return;
        }

        $handlerServices = [
            'http_kernel' => new Reference('http_kernel'),
            'router' => new Reference('router'),
            'api_platform.mcp.operation_metadata_factory' => new Reference('api_platform.mcp.operation_metadata_factory'),
        ];

        $serviceLocatorRef = ServiceLocatorTagPass::register($container, $handlerServices);
        $container->getDefinition('api_platform.mcp.server.builder')
            ->addMethodCall('setContainer', [$serviceLocatorRef]);
    }
}

I'll keep that here in case we rollback to this implementation.

Note the mcp-bundle is still not released and the php-sdk development is heavily active therefore we should expect things to break, use this at your own risk.

@soyuka
Copy link
Member Author

soyuka commented Nov 4, 2025

After further architectural review, I've decided not to move forward with this approach. This implementation attempts to statically map every API operation to an MCP tool at build time. We've found this creates a fundamental conflict with the dynamic, state-dependent nature of a hypermedia (HATEOAS) API.

This static mapping can lead to a significant mismatch where the AI is offered a tool for an action that isn't actually available (as an affordance) in the application's current state, leading to a confusing and error-prone experience. It also blurs the important protocol-level line between MCP's "application-controlled resources" and "model-controlled tools."

We are closing this in favor of a new, dynamic gateway architecture that will discover and expose tools in real-time as they become available through hypermedia controls.

@soyuka soyuka closed this Nov 4, 2025
@daFish
Copy link
Contributor

daFish commented Nov 4, 2025

@soyuka Would the new dynamic approach allow for grouping various endpoints into a single tool to avoid bloating the context by exposing too much tools?

@soyuka
Copy link
Member Author

soyuka commented Nov 4, 2025

To be more precise I'm working on two things:

  1. a MCP bundle integration - basically all the power to the user but on top of the API Platform tools (json-schema, validation, processor etc.) instead of the mcp handlers
  2. a hypermedia mcp approach - a research project that we don't know yet if it is going to be worth something :) this will probably not be embeded into the core of API Platform

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants