PrefectHQ/fastmcp · error · TypeError

mcp_prompt() got unexpected keyword argument(s): {sorted(unk

Error message

mcp_prompt() got unexpected keyword argument(s): {sorted(unknown)!r}. Valid keyword arguments are: {sorted(_PROMPT_VALID_KWARGS)}

What it means

mcp_prompt() validates its keyword arguments at decoration time against the live parameter set of Prompt.from_function. Unknown keywords raise this TypeError immediately so invalid decorator usage fails at import, not at server startup.

Source

Thrown at fastmcp_slim/fastmcp/contrib/mcp_mixin/mcp_mixin.py:154

    Accepts all parameters supported by ``Prompt.from_function``.  Any new
    parameters added to ``Prompt.from_function`` are automatically forwarded
    without requiring changes here.

    Args:
        name: Prompt name.  Defaults to the decorated method name.
        enabled: If ``False``, the prompt is skipped during registration.
        **kwargs: Additional keyword arguments forwarded verbatim to
            ``Prompt.from_function`` (e.g. ``description``, ``tags``,
            ``auth``, ``version``, …).

    Raises:
        TypeError: If an unrecognised keyword argument is supplied.  The error
            is raised immediately at decoration time rather than later.
    """
    unknown = set(kwargs) - _PROMPT_VALID_KWARGS
    if unknown:
        raise TypeError(
            f"mcp_prompt() got unexpected keyword argument(s): {sorted(unknown)!r}. "
            f"Valid keyword arguments are: {sorted(_PROMPT_VALID_KWARGS)}"
        )

    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        call_args: dict[str, Any] = {"name": name or get_fn_name(func), **kwargs}
        if enabled is not None:
            call_args[_MIXIN_ENABLED_KEY] = enabled
        setattr(func, _MCP_REGISTRATION_PROMPT_ATTR, call_args)
        return func

    return decorator


class MCPMixin:
    """Base mixin class for objects that can register tools, resources, and prompts
    with a FastMCP server instance using decorators.

View on GitHub (pinned to 1f02114297)

Solutions

1. Correct or remove the kwarg(s) named in the message, using the listed valid kwargs
2. Verify against inspect.signature(Prompt.from_function) for your installed version
3. Fix misspellings (descripton -> description)
4. Move layer-specific options out of mcp_prompt() to where they belong

Example fix

// before
@mcp_prompt(name="review", descripton="Code review prompt")
def review(self, code: str) -> str: ...

// after
@mcp_prompt(name="review", description="Code review prompt")
def review(self, code: str) -> str: ...

import inspect
from fastmcp.prompts.base import Prompt
valid = set(inspect.signature(Prompt.from_function).parameters) - {"fn"}
bad = set(my_kwargs) - valid
if bad:
    raise TypeError(f"Invalid mcp_prompt kwargs: {bad}")

def has_valid_prompt_kwargs(kwargs: dict) -> bool:
    import inspect
    from fastmcp.prompts.base import Prompt
    valid = set(inspect.signature(Prompt.from_function).parameters) - {"fn"}
    return set(kwargs) <= valid

When it happens

Trigger: Decorating a class method with @mcp_prompt(...) and passing a kwarg Prompt.from_function does not accept — misspellings, options removed/renamed in a newer fastmcp, or kwargs copied from the tool/resource decorators that prompts don't support.

Common situations: Upgrading fastmcp where Prompt.from_function changed; copy-pasting decorator kwargs between mcp_tool/mcp_resource/mcp_prompt; typos like `descripton=`.

Related errors

• mcp_tool() got unexpected keyword argument(s): {sorted(unkno
• mcp_resource() got unexpected keyword argument(s): {sorted(u
• Expected Resource, ResourceTemplate, or @resource-decorated
• First argument to @tool must be a function, string, or None,
• Protocol mode for server {name!r} must be a string

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