Framework-level MCP server: agent-friendly tool discovery for Reflex apps

[masenf]

Investigate and design the optimal way for AI agents to interact with a Reflex app via MCP, particularly apps with large surfaces (hundreds of event handlers).

Problem

The naive approach — expose every event handler as a separate MCP tool — breaks down at scale. A Reflex app with hundreds of event handlers would produce an enormous OpenAPI spec, and if each handler became its own tool, the agent's context would be polluted with irrelevant options. The agent can't effectively choose from 300 tools when it only needs 2 for the current request.

Just supporting an HTTP endpoint for every event handler (ENG-9179, section 1f) and generating the associated OpenAPI spec isn't enough to make a Reflex app agent-friendly. The machinery for calling events is necessary but not sufficient — agents also need a way to efficiently discover which events are relevant.

Investigation Areas

Tool Discovery Over Tool Enumeration

Rather than registering every event handler as a separate MCP tool, the MCP server should expose a small, fixed set of meta-tools:

• Search/discover events — given a natural language description of what the agent wants to do, return matching event handlers with their signatures and descriptions. This is where @rx.event docstrings, type annotations, and any explicit description= metadata become critical.
• Call event — a single generic tool that invokes any event handler by name with the appropriate arguments. The agent uses the search tool to find the right handler, then calls it through this generic interface.

This keeps the agent's tool count constant (2–3 tools) regardless of app size, while still providing full access to the app's capabilities.

Metadata & Discoverability

For search to work well, event handlers need rich metadata:

• Docstrings on @rx.event functions become the searchable descriptions
• Type annotations on handler arguments become the parameter schema
• Grouping/tagging (e.g. by state class, by domain) helps narrow search results
• The OpenAPI spec (ENG-9179 1f) provides the structured schema, but the MCP layer adds the discovery/search interface on top

Context Management for Large Apps

• How should the MCP server handle apps where even search results are large?
• Should there be a "list categories/states" tool that lets agents narrow scope before searching?
• How does this compose with multi-state apps where different states represent different domains?

Streaming & Intermediate State

• How should long-running event handlers report progress to agents?
• The NDJSON streaming mode from HTTP endpoints (1f) is relevant here — can MCP tool responses stream intermediate deltas?

Prior Art & References

• Stop Converting REST APIs to MCP — argues against 1:1 endpoint-to-tool mapping
• ENG-9179 — Event System & State Management (HTTP endpoints, OpenAPI spec in section 1f)
• ENG-9189 — Interoperability & Standardization (ASGI layer the MCP server would sit on top of)

Expected Output

A design document or RFC covering:

1. The recommended MCP tool surface for a Reflex app (which tools, what they do)
2. How event handler metadata feeds into discovery
3. How this scales from a 5-handler demo app to a 500-handler production app
4. What framework-level APIs or decorators are needed to support this

Roadmap

Part of the Reflex Framework Roadmap — AI & MCP Integration section.

[linear]

ENG-9191

[itsmeadarsh2008]

https://github.com/itsmeadarsh2008/reflex-docs-mcp
I maintain this fork; this might be helpful for you.
Note: some tools don't work, like get_changelog, and the migration guide doesn't really work, kept as dead code because the current repo doesn't have a CHANGELOG.md in it's root.

[Alek99]

https://github.com/itsmeadarsh2008/reflex-docs-mcp I maintain this fork; this might be helpful for you. Note: some tools don't work, like get_changelog, and the migration guide doesn't really work, kept as dead code because the current repo doesn't have a CHANGELOG.md in it's root.

No this is a different thing we are working on making reflex apps have a mcp server by default, not an mcp server for reflex

[itsmeadarsh2008]

itsmeadarsh2008/reflex-docs-mcp I maintain this fork; this might be helpful for you. Note: some tools don't work, like get_changelog, and the migration guide doesn't really work, kept as dead code because the current repo doesn't have a CHANGELOG.md in it's root.

No this is a different thing we are working on making reflex apps have a mcp server by default, not an mcp server for reflex

Oh, I got it. So it is basically to provide better onboarding knowledge to AI Agents.