Summary
Extend the first-party agent (FF Expert) to receive tool list and tool execution requests from the Forge backend over a dedicated MCP MQTT topic namespace, and respond with results. This is the agent-side counterpart to #7560.
Why
The Forge backend's MCP endpoint is the single entry point for 3rd party agents. For agent tools (flow/NR tools, frontend tools), it proxies requests to the expert agent via MQTT. The expert agent already has all the internal plumbing (MQTT inflight, browser session management, NR iframe communication), it needs a new MQTT interface for the Forge backend to call.
MQTT is chosen over HTTP because:
- The expert agent already communicates over MQTT
- Horizontal scaling (multiple agent instances can subscribe to the same topics)
- Per-customer isolation is easier with MQTT topic namespacing
- The infrastructure (EMQX, bridges, ACL) is already in place
What to do
MQTT topic structure (agent side)
The agent subscribes to request topics and publishes on response topics:
Subscribe: ff/v1/mcp/+/<userId>/<sessionId>/<entityType>/<entityId>/req
Publish: ff/v1/mcp/<platformId>/<userId>/<sessionId>/<entityType>/<entityId>/res
The + wildcard on <platformId> means the agent receives requests from any Forge instance. The <platformId> is extracted from the request payload or topic and included in the response topic so it routes back to the correct Forge instance.
Subscription management
- Agent subscribes per user/session/entity combination as they become active
- Subscriptions cached with in-process LRU (
lru-cache directly), ~24h TTL, extend on reuse, unsubscribe on eviction
- ACL rules for
ff/v1/mcp/ topics: validate expert-agent client only, no user/team/RBAC checks (that's done at the Forge HTTP layer)
Tool list requests
- Agent responds to "list tools" messages with its full tool list including annotations (
readOnlyHint, destructiveHint, etc.)
- Tool list includes all tools the agent exposes: flow/NR instance tools, frontend tools (context, navigation, routes), and any other agent-defined tools
- Tool list is scoped to the requesting user's context (active instance, team, etc.)
- Correlation ID based matching for request/response
Tool execution requests
- Agent receives "execute tool" messages, executes the requested tool using its existing internal mechanisms
- For tools that need the browser (flow tools, frontend tools): the agent publishes on the existing
ff/v1/expert/ topics, which go through the normal checkExpertTopic ACL validation. The agent re-enters the existing MQTT infrastructure through the front door.
- For tools that are agent-internal (no browser needed): the agent executes directly and responds
- Response published on the corresponding
ff/v1/mcp/.../res topic with matching correlation ID
Internal routing (MCP -> expert topics)
- When a tool call arrives on the MCP topic, the agent unpacks the payload (userId, sessionId, entityType, entityId, toolName, toolInput)
- If the tool requires browser interaction, the agent constructs the appropriate
ff/v1/expert/ topic and publishes through its existing inflight mechanism
- The existing
checkExpertTopic ACL validates team membership and RBAC on the expert topic (this is the "front door" validation)
- The agent awaits the browser response on the expert response topic, then publishes the result back on the MCP response topic
Tests
- Agent responds to a tool list request with available tools including annotations
- Agent responds to a tool execution request with the result
- Tool list is scoped per user/instance context
- Correlation IDs correctly match requests to responses
- Browser-dependent tool: agent routes through existing
ff/v1/expert/ topics, result comes back on MCP response topic
- Agent-internal tool: executes directly, responds on MCP response topic
- Subscription per user/session/entity: new subscription created on first request, reused on subsequent
- Subscription TTL extended on reuse, unsubscribed on eviction
- Timeout: unresponsive browser produces a structured error on MCP response topic
References
Summary
Extend the first-party agent (FF Expert) to receive tool list and tool execution requests from the Forge backend over a dedicated MCP MQTT topic namespace, and respond with results. This is the agent-side counterpart to #7560.
Why
The Forge backend's MCP endpoint is the single entry point for 3rd party agents. For agent tools (flow/NR tools, frontend tools), it proxies requests to the expert agent via MQTT. The expert agent already has all the internal plumbing (MQTT inflight, browser session management, NR iframe communication), it needs a new MQTT interface for the Forge backend to call.
MQTT is chosen over HTTP because:
What to do
MQTT topic structure (agent side)
The agent subscribes to request topics and publishes on response topics:
The
+wildcard on<platformId>means the agent receives requests from any Forge instance. The<platformId>is extracted from the request payload or topic and included in the response topic so it routes back to the correct Forge instance.Subscription management
lru-cachedirectly), ~24h TTL, extend on reuse, unsubscribe on evictionff/v1/mcp/topics: validate expert-agent client only, no user/team/RBAC checks (that's done at the Forge HTTP layer)Tool list requests
readOnlyHint,destructiveHint, etc.)Tool execution requests
ff/v1/expert/topics, which go through the normalcheckExpertTopicACL validation. The agent re-enters the existing MQTT infrastructure through the front door.ff/v1/mcp/.../restopic with matching correlation IDInternal routing (MCP -> expert topics)
ff/v1/expert/topic and publishes through its existing inflight mechanismcheckExpertTopicACL validates team membership and RBAC on the expert topic (this is the "front door" validation)Tests
ff/v1/expert/topics, result comes back on MCP response topicReferences
forge/comms/aclManager.js(expertAgent ACLs)ff/v1/expert/topic namespace