Skip to content

2.2.0: several servers, tool catalog, MCP Apps, MCP client - #3

Draft
ajibarra wants to merge 181 commits into
2.next-cake5from
feature/2.2
Draft

ajibarra wants to merge 181 commits into
2.next-cake5from
feature/2.2

Conversation

@ajibarra

@ajibarra ajibarra commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Version 2.2.0. A 2.1 application keeps working without config or code changes. A few behaviour changes can still be noticed, all listed at the top of CHANGELOG.md (among them: the registry is loaded before authentication, initialize announces exactly what the server has, mcpCallTool() sends a progress token, McpConfig::isEndpoint() reads the path as the router does). Every new feature is off until configured.

What is new

Servers

  • Several MCP servers in one application (Mcp.servers), each with its own route, metadata route, tools, auth and authorizer. Security sections are replaced whole (with mode and authorizer required), identity is never inherited, an inherited auth gets the server's own resource, the rest is inherited key by key. A mistake in one entry stops that entry only, is logged, and mcp check reports it.
  • Routes with parameters (/mcp/t/{tenant}): one config and one set of tools for every value, the value available to tools through McpRoute; in OAuth modes each value is its own resource, so a token for one value is refused for another.
  • Named servers served over stdio only ('route' => false).
  • Cache hints of the 2026-07-28 protocol (Mcp.server.cache), always private on a per-user tools/list.
  • Mcp.schema.normalize for hosts that reject type arrays; Mcp.server.icons.
  • An Mcp-* header with invalid UTF-8 answers 400.

Tools, resources and prompts

  • Tool catalog (Mcp.catalog): chosen tools leave tools/list and are reached through find_tools and call_tools. Every inner call goes through the authorizer, the tool scopes, the input schema and the audit log (via=call_tools), like a direct tools/call.
  • Authorization of resources and prompts: an authorizer may implement ResourceAuthorizerInterface and PromptAuthorizerInterface. Denied elements are hidden from the lists and answer like unknown ones on read, get, subscribe, unsubscribe and completion, and a subscriptions/listen stream carries no update for them; a denied template denies the URIs it serves. RbacToolAuthorizer supports them only once a rule names them, so 2.1 rule sets change nothing.
  • #[McpWhen]: register a tool, resource, template or prompt only when a config value is on or a callback returns true.
  • ToolValidation::check() and checkPrompt() with a Cake Validator; ToolError::message().
  • Progress and log notifications from tools.
  • Bake: mcp_tool, mcp_resource, mcp_prompt and mcp_app, each with its test.

MCP Apps (Mcp.apps.enabled)

  • AppView::render() renders an app page from a Cake template, in a layout that inlines the official MCP Apps client (@modelcontextprotocol/ext-apps 2.0.4, vendored with its license in resources/ext-apps).
  • #[McpApp] links a tool to its app. App-only tools are left out of tools/list for clients that do not render apps, and tools with an app never go behind the catalog. They still go through the authorizer, scopes and audit (app=1).

MCP client (Mcp.clients)

  • McpClients::get('name') calls tools, resources and prompts of other MCP servers, over HTTP (token, callable token or headers) or a local stdio server, with tools.only / tools.except, ping(), serverInfo(), capabilities(), instructions(), list limits, one retry when the server refused the call before running it (an expired session, a header mismatch, a 401 answered with a fresh token), and an optional list cache that follows the server's cache hints and keys private lists by the credential they were asked with.
  • User mode ('auth' => 'user'): each user connects their own account through OAuth (RFC 9728 and 8414 discovery, Client ID Metadata Document on a site authorization servers can reach, otherwise dynamic registration, PKCE, resource indicators, iss check, scope step-up). Tokens are stored encrypted in tables keyed by SHA-256 hashes, refreshed by one request at a time per user, and revoked on disconnect(). A configured clientSecret is bound to its issuer. Ships one migration (mcp_client_connections, mcp_client_registrations).
  • App mode with 'auth' => 'client_credentials'.
  • Addresses a remote server names go through an SSRF guard that pins the resolved IP and refuses private networks, compressed answers and local names; Mcp.client.proxy and a per-client allowPrivateNetwork for corporate networks.

Testing

  • McpTestTrait: tools that report progress get a response in tests; prompts, resources and completions through the server (mcpGetPrompt(), mcpReadResource(), mcpComplete(), lists); assertions for notifications, structured content, what another identity sees, and mcpUseServer().
  • CI runs the client side of the official MCP conformance suite next to the server side.

bin/cake mcp check

  • New lines: Discovery, Tool schemas, Cache hints, Conditions, Catalog, Apps, Clients, one per named server, and checks across servers (shared routes, resources or audiences, nested scan directories, route parameters missing from a resource).

Docs

  • New pages: docs/features.md (overview), docs/resources-and-prompts.md, docs/apps.md, docs/mcp-client.md. docs/tools.md, docs/configuration.md, docs/authorization.md and docs/testing.md cover the rest. CHANGELOG.md has the full list.

Upgrading

composer update. Run bin/cake migrations migrate -p CakeDC/Mcp only if you use the MCP client in user or client_credentials mode.

Checks

  • PHPUnit: 1182 tests passing. PHPStan level 8 and phpcs (CakePHP standard): clean.
  • The official MCP conformance suite, server and client side, passes against its baselines.
  • The 2.1 test suite (369 tests) passes against this code except one test, on purpose: a call whose authorizer throws is now still audited, where 2.1 dropped the record (listed in CHANGELOG.md). The migration was run up, down and up again on SQLite, MySQL 8.4, MariaDB 11.8 and PostgreSQL 17.

Known limits (left on purpose)

  • Two first saves of the same user's grant at the same time both succeed and the last one wins (checked with real processes on MySQL 8.4, MariaDB 11.8 and PostgreSQL 17). Inside a transaction the application opened itself, such a collision still throws: MySQL and MariaDB do not see the other row, and PostgreSQL aborts the transaction after the first error. Same as before the fix.
  • Two first dynamic registrations at once with an authorization server that issues a client secret: the last one is kept, so the other sign-in fails with invalid_client, the stored registration is dropped, and both users connect again. With a public client, which is what the plugin asks for, nothing happens.
  • On CakePHP 5.3.6 or older (and 5.2.14, 5.1.9 or older), whose router decodes the path differently, /mcp%2Fadmin counts as an endpoint before routing and is then not served (the safe direction), and two tests of the suite fail. Composer refuses those releases by default because of security advisories; the patched 5.1.10, 5.2.15 and 5.3.7 behave as expected.

Where to look first

  • Security paths: src/Catalog/ToolCatalog.php (inner calls), src/Authorization/ (resource and prompt authorization), src/McpConfig.php (inheritance between servers, route parameters), src/Client/Http/ (SSRF guard), src/Client/OAuth/ and src/Client/UserConnection.php (OAuth flow, refresh).
  • src/Server/ServerFactory.php for how servers, the catalog and conditions are built.

…er at the site's root, and is reported as a mistake
…offset, and otherwise passes on the registry's own cursor
…_PROXY decides nothing else, and socks5h is the SOCKS scheme
… slow authorization server holds a worker that long at most
…the mark, a new grant ends the old one's refresh, and two first saves both succeed
…gn-in already asked for marks nothing, so there is no redirect loop
…er and the catalog share one container bridge
…wercase, so ACME never shares acme's resource
…a timeout: curl's whole seconds are rounded up
…ept like the lists, by their hints and credential
…ult that does not fit says its tool ran, and the search reads allowed values and nested arguments
…gment that is not there, any order, the shape of keys, and a closure at a path
…s keys, and any-order lists match item by item
…d at another server gets nothing the previous one answered
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