MCP Bundle configuration

Configuration has two parts: routes define which endpoints exist and which API group and version each one serves; the ufo_mcp configuration only tunes the group's server. The configuration never decides which methods become tools or which version is served.

Routes: one import per endpoint

# config/routes/ufo_mcp.yaml
ufo_mcp:
    resource: ../../vendor/ufo-tech/mcp-bundle/config/router.yaml
    prefix: /mcp
    defaults: { api_group: mcp }

ufo_mcp_internal:
    resource: ../../vendor/ufo-tech/mcp-bundle/config/router.yaml
    prefix: /mcp/internal
    defaults: { api_group: internal }

• api_group is the core API group the endpoint serves. Without it, the core default group general is used.
• Every import gets its own route names (mcp_ufo_mcp_endpoint, internal_ufo_mcp_endpoint, …), so name_prefix is not needed. The core route loader does this for YAML imports; in PHP or XML route configuration set name_prefix by hand.

Every import serves:

{ver} is v1, v2, …; without it, v1.

Configuration reference

File config/packages/ufo_mcp.yaml, root key ufo_mcp.

ufo_mcp:
    enabled: true
    instructions: ~
    max_body_bytes: 4194304
    session_ttl: 3600
    mcp_server_info:
        name: 'io.github.your-org/your-app'
        title: 'Your App MCP Server'
        description: 'Exposes Your App RPC services as MCP tools.'
        icons:
            - src: 'https://example.com/icon.png'
              mime_type: 'image/png'
              sizes: ['128x128']
              theme: ~
    groups:
        internal:
            instructions: 'Internal tools.'
            mcp_server_info:
                name: 'io.github.your-org/your-app-internal'

• groups is optional. The route defines the group; a group without its own entry runs on the bundle-wide settings. An entry only overrides them field by field: an unset (or ~) field inherits the bundle-wide value, mcp_server_info too (a group may set only name).
• There is no version setting. serverInfo.version in initialize and version in server.json are always the request's {ver}.
• Options of earlier builds (session_directory, server_name, server_version, methods) were removed; with them the configuration fails with "Unrecognized option".

API groups

The core #[RPC\APIGroups] attribute on a class or method decides which methods become tools:

use Ufo\RpcObject\RPC;

#[RPC\Info('Catalog')]
#[RPC\APIGroups(['mcp', 'internal'], withDefault: false)]
final class CatalogProcedure implements IRpcService { /* /mcp and /mcp/internal, not /rpc */ }

#[RPC\Info('Admin')]
#[RPC\APIGroups(['internal'], withDefault: false)]
final class AdminProcedure implements IRpcService { /* only /mcp/internal */ }

The same group can be served by /rpc/... (JsonRpcBundle) and /mcp/... (this bundle) at the same time. Token checks for the group (ufo_json_rpc.security.providers) apply to MCP as well.

API versions

/mcp and /mcp/v1 serve version 1, /mcp/v2 serves version 2 of the group in the core (#[RPC\Info('Catalog', version: 2, removedMethods: [...])]; a version inherits the previous one, see API versions). A version the group does not have answers 404. A group without any method answers 404 too.

Sessions and a shared cache

Clients of the session-based protocol (before 2026-07-28) get an Mcp-Session-Id. The session is stored in the core cache pool under the key ufo_mcp_<group>_<session id> with the group's session_ttl. By default this is a local filesystem pool; when several hosts serve MCP, point it to a shared store, otherwise a session created on one host is unknown on another:

# config/packages/ufo_json_rpc.yaml
ufo_json_rpc:
    cache:
        pool: 'cache.app'   # e.g. a shared Redis

Stateless clients of the 2026-07-28 protocol do not need session storage.