Capability Matrix

Measured on: 2026-09-05 against main and the production deployment. Tracking issue: #9720. Readiness review: #9714.

This is the accurate statement of which capability works today through which entry point. It replaces the README's former claim that "every capability" is exposed and controllable via MCP. Every row below carries one status per entry point; a status that is not proven names the issue that tracks the gap, and a status of excluded says why in the Notes column.

The four entry points:

Legend

Facts this matrix reflects (verified 2026-09-05)

• **Production has no PLATFORM_* generation keys ([#9117](https://github.com/Tristan578/project-forge/issues/9117)). Every generation capability served by the platform's own key is `unavailable` for platform users. Settings → API Keys offers four BYOK providers (`BYOK_PROVIDERS` in `web/src/lib/config/providers.ts`: Anthropic, Meshy, Hyper3D, ElevenLabs), and three of them work: a user's own Meshy key serves 3D models and textures, an ElevenLabs key serves sound effects, voice and music, an Anthropic key serves chat. A stored Hyper3D key is never consumed — `/api/generate/model` resolves `DB_PROVIDER.model3d`, which is Meshy, and no route reads the Hyper3D key. Suno** is no longer offered (#9522): it is a retired provider (RETIRED_BYOK_PROVIDERS) — no new Suno key can be added, but a historical one stays removable. There is no BYOK path for OpenAI, Replicate or remove.bg.
• Music is served by ElevenLabs (#9522): music moved off Suno (which has no public API and could never be provisioned) to ElevenLabs, the same provider that already serves sfx and voice — one ElevenLabs key covers all three. music is no longer in UNAVAILABLE_CAPABILITIES, so it behaves exactly like the other two ElevenLabs capabilities: offered whenever PLATFORM_ELEVENLABS_KEY is set (unset in production, so unavailable (#9117) for platform users) and enabled for any user with a BYOK ElevenLabs key. /api/generate/music resolves the audio inline through ElevenLabs. PLATFORM_SUNO_KEY was removed from the codebase.
• External MCP cannot reach production (#9722): NEXT_PUBLIC_MCP_BRIDGE is absent from the production build, so mcpBridgeEnabled() (web/src/lib/mcp/bridgeOptIn.ts) is false and no external client can attach. Every External MCP cell whose category the bridge would execute is unavailable until that decision lands. In a local build — or a production build made with NEXT_PUBLIC_MCP_BRIDGE=true — the relay attaches to a tab opened with ?mcp=<token> after the in-tab consent prompt and executes through the same handler registry as the in-app AI, filtered by the bridge allowlist: the six categories bridgeAllowlist.ts denies are excluded here because that is a design decision, not a gate. That local path is itself unverified end to end.
• The public MCP reference is down: docs.spawnforge.ai/mcp returns 500 (#9718); the fix is PR #9730, open and unmerged.
• Phantom script commands (#9284): 16 names in SCRIPT_ALLOWED_COMMANDS have no engine arm: set_velocity, set_velocity2d, set_angular_velocity2d, set_music_intensity, set_music_stems, all four sprite-animation names (play_sprite_animation, stop_sprite_animation, set_sprite_anim_speed, set_sprite_anim_param), all four camera_* names, stop_skeletal_animation2d, set_ik_target2d and vibrate. A script calling one gets no error and no effect, because dispatchCommand returns void. Rows whose scripting surface includes one of these are partial (#9284), or unavailable (#9284) when every name is a phantom. The forge.* functions that dispatch them are named in each row's Notes.
• Declared script namespaces are now built (#9733, resolved): forgeTypes.ts declares forge.i18n and forge.leaderboard, and scriptWorker.ts now builds both — a call no longer throws TypeError. forge.i18n (scriptWorker.ts:1147) resolves synchronously against locale bundles shipped in the worker init message from the editor store's localization slice (useScriptRunner.ts init payload); forge.leaderboard (scriptWorker.ts:1132) routes submit/getTop through the new leaderboard async channel (channels/leaderboardChannel.ts:41), backed by /api/play/[userId]/[slug]/leaderboard. Unit tests: scriptWorker.test.ts ("forge.i18n.t returns the translation…", "forge.leaderboard.submit resolves with the rank…"), leaderboardChannel.test.ts, useScriptRunner.test.ts ("registers the leaderboard channel…"). Runtime limit: the script worker runs only in the editor's test-play (useScriptRunner), which carries no published-game identity, so forge.leaderboard rejects with "only available when playing a published game" there; it succeeds only once a published play host runs the worker with a real userId/slug.
• Manifest size: mcp-server/manifest/commands.json holds 374 commands across 41 categories, 301 public and 73 internal (jq '.commands | length' mcp-server/manifest/commands.json). Command *registration* is 374/374 (web/src/stores/slices/__tests__/commandArmParity.test.ts, web/src/lib/chat/__tests__/manifestHandlerParity.test.ts); registration is not runtime parity, which is why most cells below are implemented-unverified rather than proven. These counts, and the per-category counts in the Notes column below, are compared against the manifest by the gate named at the end of this file.

Generation capabilities

One row per entry in PROVIDER_CAPABILITIES (web/src/lib/config/providers.ts). Provider per capability is DIRECT_CAPABILITY_PROVIDER; the platform key each provider needs is PLATFORM_KEY_ENV. Every External MCP cell in this table is excluded: the bridge allowlist denies the generation category and the ai:generate scope, so no generation command is reachable over the bridge even in a local build.

Command categories

One row per category value in mcp-server/manifest/commands.json. The count is public/internal commands in that category. "Chat-exposed" means getChatTools() offers the command to the model (a :write scope, or the query category). An External MCP cell is excluded exactly when BRIDGE_DENIED_CATEGORIES in bridgeAllowlist.ts names the category; every other External MCP cell is unavailable (#9722) because the bridge cannot attach to production.

How this file is checked

web/src/lib/config/__tests__/capabilityMatrix.test.ts reads this file and runs in the web unit-test gate, which .github/workflows/ci.yml fires for an edit to this file alone (scripts/__tests__/ci-gate-path-filters.test.sh pins that). It fails when:

• a PROVIDER_CAPABILITIES entry has no generation:<capability> row, or a manifest category has no commands:<category> row;
• a row names a capability or category that no longer exists;
• any of the four entry-point cells is not exactly one of the five statuses, optionally followed by (#issue) or (#issue, #issue);
• a partial, unavailable or implemented-unverified cell carries no issue reference, or a proven cell carries one (evidence for proven belongs in Notes);
• a row with an excluded cell has an empty Notes column;
• the table under the ## Legend heading stops defining one of the five statuses;
• the manifest counts in the Facts section (374 commands, 41 categories, 301 public, 73 internal) or a commands: row's leading public/internal count in Notes disagree with mcp-server/manifest/commands.json;
• a generation:music cell other than External MCP is anything but unavailable (#9117) — since #9522 moved music to ElevenLabs it follows PLATFORM_ELEVENLABS_KEY exactly like sfx and voice;
• an External MCP cell is not excluded for a category BRIDGE_DENIED_CATEGORIES names, or is anything but unavailable (#9722) for a category the bridge allows — those pins are removed in the same change that closes the issue;
• apps/docs/data/capability-matrix.json, the copy the docs site renders at /capability-matrix, does not reproduce this file line for line. Regenerate it with npm run sync:capability-matrix from the repo root; the docs gate (apps/docs/scripts/check-manifest-sync.ts) checks the same thing.

The same suite also pins README.md's command counts — the manifest total, category and public counts, the getChatTools() count the in-app AI is offered, and the bridgeAllowedCommands() count the MCP bridge executes — against the code that produces them, and sweeps the file for any other three-digit count on a line that mentions commands. The README's "350" rotted because that number was prose too.

The walk fails closed: an unreadable file, zero rows, or a header missing one of the four columns is a failure, never a pass. To add a row, copy an existing one and change every cell you can stand behind. To promote a cell to proven, name the CI-run spec or the production check in Notes.