Open issues

Known bugs and inconsistencies in the current version of MCP Bundle (1.0.0): symptom, cause and workaround. Core issues are in the JsonRpcBundle known issues. Fixed ones are on the Fixed issues page.

<include>(.issues/group-limits-not-validated.md)

<include>(.issues/oauth-not-supported.md)

<include>(.issues/xdebug-coverage-segfault.md)

<include>(.issues/bundle-docs-inconsistencies.md)

Group limits are not validated by the configuration

Symptom. The bundle-wide max_body_bytes and session_ttl must be integers >= 1, otherwise the container does not build. The same parameters under groups.<group> accept anything, and the error shows up only at request time:

• max_body_bytes: 0 (or negative): every request to the group's endpoint fails with HTTP 500 (maxBodyBytes must be at least 1. from the SDK transport);
• session_ttl: 0 or negative: a session expires right after it is created, and a session-based client gets 404 on every request after initialize;
• a string instead of a number: a TypeError when the bundle configuration is created, HTTP 500.

Cause. In Configuration, these group fields are scalarNode without min(1) (so that ~ is accepted as "inherit"), and McpGroupConfig assigns the values without a check.

Workaround. Set integers >= 1 for the group or leave the field out (then the bundle-wide value applies). For environment variables use %env(int:...)%.

OAuth-only clients cannot connect

Symptom. An MCP client that cannot send a custom header and expects OAuth authorization gets 401 and does not connect. For example, MCP Inspector without the token header starts its own OAuth flow, which fails.

Cause. OAuth is not implemented: there is no /.well-known/oauth-protected-resource and no WWW-Authenticate header in the 401 response. Access is only the core RPC token in a header (Ufo-RPC-Token).

Workaround. Use clients that support custom headers (Claude Code, Cursor, Gemini CLI, OpenAI Responses API) and the manifests; in MCP Inspector pass --header "Ufo-RPC-Token: …".

Coverage under Xdebug ends in a segmentation fault

Symptom. Running the tests with coverage through Xdebug 3.4.2 (image ufotech/php:8.4-fpm) crashes with a segmentation fault on the tests that start the SDK server.

Cause. A crash of Xdebug 3.4.2 itself, not a bug in the bundle code (according to the 1.0 release notes); the exact cause is not established.

Workaround. Collect coverage with pcov; see Testing.

Inconsistencies in the bundle repository documentation

• The bundle's README.md and README-UA.md link to the documentation at http://localhost/uk/docs/api/mcp-bundle. The up-to-date documentation is on this site.
• The "In one minute" example in docs/README.md (and -UA) promises a Catalog.search tool for a CatalogProcedure class without #[RPC\Info]. Without the attribute the core uses the short class name, so the tool is named CatalogProcedure.search. To get Catalog.search, add #[RPC\Info('Catalog')], as in the examples on this site.