PrefectHQ/fastmcp · error

visibility cannot be set on resources — it only applies to t

Error message

visibility cannot be set on resources — it only applies to tools.

What it means

The @mcp.resource decorator rejects an AppConfig with a non-None visibility setting, because visibility controls only apply to tools, not resources. Configuration-time ValueError.

Source

Thrown at fastmcp_slim/fastmcp/server/server.py:2061

                "The @resource decorator was used incorrectly. "
                "It requires a URI as the first argument. "
                "Use @resource('uri') instead of @resource"
            )

        # Apply default MIME type for ui:// scheme resources
        mime_type = resolve_ui_mime_type(uri, mime_type)

        # Validate app config for resources — resource_uri and visibility
        # don't apply since the resource itself is the UI
        if isinstance(app, AppConfig):
            if app.resource_uri is not None:
                raise ValueError(
                    "resource_uri cannot be set on resources — "
                    "the resource itself is the UI. "
                    "Use resource_uri on tools to point to a UI resource."
                )
            if app.visibility is not None:
                raise ValueError(
                    "visibility cannot be set on resources — it only applies to tools."
                )

        # Merge app config into meta["ui"] (wire format) before passing to provider
        if app is not None and app is not False:
            meta = dict(meta) if meta else {}
            if app is True:
                meta["ui"] = True
            else:
                meta["ui"] = app_config_to_meta_dict(app)

        # Delegate to LocalProvider with server-level defaults
        inner_decorator = self._local_provider.resource(
            uri,
            name=name,
            version=version,
            title=title,
            description=description,

View on GitHub (pinned to 1f02114297)

Solutions

1. Remove visibility from the AppConfig on the resource
2. Control resource access via providers/middleware/auth instead of visibility
3. Give resources their own AppConfig (or app=None/False) separate from tools

Example fix

// before
@mcp.resource("data://metrics", app=AppConfig(visibility="private"))
def metrics(): ...
// after
@mcp.resource("data://metrics")
def metrics(): ...

if isinstance(app, AppConfig) and app.visibility is not None:
    raise ValueError("visibility is tool-only; remove it for resources")

When it happens

Trigger: Passing app=AppConfig(visibility="private" or similar) to mcp.resource() or a resource template decorator.

Common situations: Sharing one AppConfig across tools and resources; assuming visibility governs resource access control (it doesn't — use auth/middleware for resources).

Related errors

• resource_uri cannot be set on resources — the resource itsel
• contents[{i}] must be ResourceContent, got {type(item).__nam
• contents must be str, bytes, or list[ResourceContent], got {
• Either name or uri must be provided
• Subclasses must implement read()

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/9a61b8cc1de29439. Report an issue: GitHub.