Add authorization checks to components and servers by jlowin · Pull Request #2855 · PrefectHQ/fastmcp

jlowin · 2026-01-12T22:00:00Z

Tools, resources, and prompts can now declare authorization requirements using callable checks. When a component has auth configured, it's filtered from list responses for unauthorized clients and enforcement happens at access time.

from fastmcp import FastMCP
from fastmcp.server.auth import require_auth, require_scopes

mcp = FastMCP()

@mcp.tool(auth=require_auth)
def protected_tool(): ...

@mcp.resource("data://secret", auth=require_scopes("read"))
def secret_data(): ...

@mcp.prompt(auth=require_auth)
def admin_prompt(): ...

AuthMiddleware provides server-wide enforcement for all component types. restrict_tag is useful there for tag-based policies:

from fastmcp.server.middleware import AuthMiddleware
from fastmcp.server.auth import restrict_tag

# Components tagged "admin" require "admin" scope
mcp = FastMCP(middleware=[AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))])

Tools can now specify auth checks via the `auth` parameter: ```python @mcp.tool(auth=require_auth) def protected_tool(): ... @mcp.tool(auth=require_scopes("admin")) def admin_tool(): ... ``` Auth checks filter tools from list_tools and enforce at call_tool time. STDIO transport bypasses all auth (no OAuth concept in local transport). AuthMiddleware provides server-wide enforcement.

marvin-context-protocol · 2026-01-12T22:02:29Z

Test Failure Analysis

Summary: Two tests fail with AccessToken type conversion error when listing tools and calling tools via OAuth authentication.

Root Cause: The get_access_token() function in src/fastmcp/server/dependencies.py fails to convert the SDK's AccessToken to FastMCP's AccessToken because it passes claims=None, which violates FastMCP's AccessToken field constraint that expects a dict.

FastMCP's AccessToken (line 43-46 in src/fastmcp/server/auth/auth.py) extends the MCP SDK's AccessToken and adds a claims field with default_factory=dict. When converting from SDK AccessToken to FastMCP AccessToken, the code tries to pass claims=None (line 420 in dependencies.py), but Pydantic validation fails because None is not a valid dict.

Suggested Solution:

Fix src/fastmcp/server/dependencies.py:420 to handle the missing claims field properly:

# Change line 420 from:
claims=access_token_as_dict.get("claims"),

# To:
claims=access_token_as_dict.get("claims", {}),

This ensures that when claims is missing from the SDK AccessToken, we pass an empty dict instead of None, which matches the default_factory behavior.

Detailed Analysis

Failing Tests

tests/client/auth/test_oauth_client.py::test_list_tools
tests/client/auth/test_oauth_client.py::test_call_tool

Both fail with:

mcp.shared.exceptions.McpError: Expected fastmcp.server.auth.auth.AccessToken, 
got AccessToken. Ensure the SDK is using the correct AccessToken type.

Error Location

src/fastmcp/server/dependencies.py:424 raises the TypeError when the conversion at lines 412-421 fails.

Why It Fails

When an OAuth client connects:

The MCP SDK's bearer auth returns an SDK AccessToken object
get_access_token() retrieves it and attempts conversion (lines 411-421)

The code does access_token_as_dict = access_token.model_dump() which returns:

{
  "token": "...",
  "client_id": "...",
  "scopes": [...],
  "expires_at": None,
  "resource": None
  # Note: no "claims" field - SDK AccessToken doesn't have it
}

When constructing FastMCP AccessToken, it passes claims=None
Pydantic validation fails: claims must be a dict, not None

Verification

from mcp.server.auth.provider import AccessToken as SDKAccessToken
from fastmcp.server.auth.auth import AccessToken as FastMCPAccessToken

sdk_token = SDKAccessToken(token="test", client_id="client123", scopes=["read"])
access_token_as_dict = sdk_token.model_dump()
print(access_token_as_dict)
# {'token': 'test', 'client_id': 'client123', 'scopes': ['read'], 'expires_at': None, 'resource': None}

# This fails with ValidationError:
FastMCPAccessToken(**access_token_as_dict, claims=None)
# ValidationError: claims - Input should be a valid dictionary [type=dict_type, input_value=None]

# This works:
FastMCPAccessToken(**access_token_as_dict, claims={})
# Success!

Related Files

src/fastmcp/server/dependencies.py:420 - Line that needs the fix
src/fastmcp/server/auth/auth.py:43-46 - FastMCP AccessToken class definition with claims field
tests/client/auth/test_oauth_client.py:79,87 - Failing tests
src/fastmcp/server/middleware/authorization.py:98,136 - Calls get_access_token()
src/fastmcp/server/server.py:869,906 - Also calls get_access_token()

Note: This analysis addresses the test failures. There are also static analysis failures (ruff lambda check and loq file size limits) that were analyzed in my previous comment and need to be addressed separately.

🤖 Updated analysis by Marvin - Run 20936464286

coderabbitai · 2026-01-12T22:04:31Z

Walkthrough

This PR introduces a comprehensive callable-based authorization system for FastMCP. It adds a new AuthorizationError exception, an authorization module with AuthContext dataclass and built-in checks (require_auth, require_scopes, restrict_tag), an AuthMiddleware class for server-wide enforcement, and extends tools, resources, and prompts with per-component auth parameter support. The authorization utilities are exported from the auth and middleware packages, integrated into the server and provider implementations, and documented with usage examples.

Possibly related PRs

Unify component storage in LocalProvider #2680: Modifies LocalProvider.tool and FastMCP.tool decorator signatures and implementation paths, same as this PR's authorization parameter threading.
Introduce ResourceResult as canonical resource return type #2734: Changes Resource/FunctionResource and from_function signatures in the resource subsystem, overlapping with this PR's resource auth field and propagation logic.

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides clear examples of the new authorization feature but lacks required checklist completions (all checkboxes are unchecked) and does not include self-review or review-ready confirmations.	Complete all checkboxes in both Contributors and Review checklists to confirm issue tracking, testing, documentation, self-review, and review readiness before merging.
Docstring Coverage	⚠️ Warning	Docstring coverage is 70.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding authorization checks to components and servers, which is the primary focus of the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/fastmcp/server/server.py (1)
863-888: AuthorizationError from auth checks will propagate and break get_tools().

The code at lines 880-882 calls run_auth_checks() without error handling. Since run_auth_checks() explicitly re-raises AuthorizationError (allowing auth checks to signal explicit denial with a custom message), any AuthorizationError raised during the loop will propagate up and fail the entire get_tools() call.

However, the test suite demonstrates the intended behavior is silent filtering—unauthorized tools should simply not appear in the returned list. Tools failing auth checks that return False are correctly skipped via continue, but auth checks that raise AuthorizationError will break the entire request.

Wrap the run_auth_checks() call in a try-except that catches AuthorizationError and treats it like a False return (continue to the next tool):
if not is_stdio and tool.auth is not None:
    ctx = AuthContext(token=token, tool=tool)
    try:
        if not run_auth_checks(tool.auth, ctx):
            continue
    except AuthorizationError:
        continue

🧹 Nitpick comments (2)

src/fastmcp/server/providers/local_provider.py (1)
415-454: Consider documenting the auth parameter.

The docstring documents most parameters but omits auth. For consistency with other documented parameters, consider adding:
auth: Optional authorization checks for the tool. Can be a single check
    or list of checks that must all pass (AND logic).
src/fastmcp/server/auth/authorization.py (1)
158-159: Consider supporting Sequence for broader input flexibility.

The current implementation only handles list explicitly. While the type annotation specifies list, users might intuitively pass tuples.
♻️ Optional: Support Sequence types
-    check_list = [checks] if not isinstance(checks, list) else checks
+    check_list = [checks] if callable(checks) and not isinstance(checks, (list, tuple)) else list(checks)
Or update the type signature to Sequence[AuthCheck] if you want to formally support this.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ebf6e3d and a17a414.

⛔ Files ignored due to path filters (2)

tests/server/auth/test_authorization.py is excluded by none and included by none
uv.lock is excluded by !**/*.lock and included by none

📒 Files selected for processing (10)

docs/servers/auth/authorization.mdx
src/fastmcp/exceptions.py
src/fastmcp/server/auth/__init__.py
src/fastmcp/server/auth/authorization.py
src/fastmcp/server/middleware/__init__.py
src/fastmcp/server/middleware/authorization.py
src/fastmcp/server/providers/local_provider.py
src/fastmcp/server/server.py
src/fastmcp/tools/tool.py
src/fastmcp/tools/tool_transform.py

🧰 Additional context used

📓 Path-based instructions (3)

src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.py: Python source code must use Python ≥3.10 with full type annotations
Never use bare except - be specific with exception types
Prioritize readable, understandable code - clarity over cleverness; avoid obfuscated or confusing patterns
Follow existing patterns and maintain consistency across the codebase

Files:

src/fastmcp/server/middleware/__init__.py
src/fastmcp/server/middleware/authorization.py
src/fastmcp/exceptions.py
src/fastmcp/server/providers/local_provider.py
src/fastmcp/tools/tool.py
src/fastmcp/server/server.py
src/fastmcp/server/auth/__init__.py
src/fastmcp/server/auth/authorization.py
src/fastmcp/tools/tool_transform.py

src/**/__init__.py

📄 CodeRabbit inference engine (AGENTS.md)

Be intentional about re-exports - don't blindly re-export everything to parent namespaces; only re-export fundamental types to fastmcp.*

Files:

src/fastmcp/server/middleware/__init__.py
src/fastmcp/server/auth/__init__.py

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/.cursor/rules/mintlify.mdc)

docs/**/*.mdx: Use clear, direct language appropriate for technical audiences
Write in second person ('you') for instructions and procedures in MDX documentation
Use active voice over passive voice in MDX technical documentation
Employ present tense for current states and future tense for outcomes in MDX documentation
Maintain consistent terminology throughout all MDX documentation
Keep sentences concise while providing necessary context in MDX documentation
Use parallel structure in lists, headings, and procedures in MDX documentation
Lead with the most important information using inverted pyramid structure in MDX documentation
Use progressive disclosure in MDX documentation: present basic concepts before advanced ones
Break complex procedures into numbered steps in MDX documentation
Include prerequisites and context before instructions in MDX documentation
Provide expected outcomes for each major step in MDX documentation
End sections with next steps or related information in MDX documentation
Use descriptive, keyword-rich headings for navigation and SEO in MDX documentation
Focus on user goals and outcomes rather than system features in MDX documentation
Anticipate common questions and address them proactively in MDX documentation
Include troubleshooting for likely failure points in MDX documentation
Provide multiple pathways (beginner vs advanced) but offer an opinionated path to avoid overwhelming users in MDX documentation
Always include complete, runnable code examples that users can copy and execute in MDX documentation
Show proper error handling and edge case management in MDX code examples
Use realistic data instead of placeholder values in MDX code examples
Include expected outputs and results for verification in MDX code examples
Test all code examples thoroughly before publishing in MDX documentation
Specify language and include filename when relevant in MDX code examples
Add explanatory comments for complex logic in MDX code examples
Document all API...

Files:

docs/servers/auth/authorization.mdx

🧠 Learnings (5)

📓 Common learnings

Learnt from: jlowin
Repo: jlowin/fastmcp PR: 0
File: :0-0
Timestamp: 2025-12-01T15:48:05.095Z
Learning: PR #2505 in fastmcp adds NEW functionality to get_access_token(): it now first checks request.scope["user"] for the token (which never existed before), then falls back to _sdk_get_access_token() (the only thing the original code did). This is not a reversal of order but entirely new functionality to fix stale token issues.

📚 Learning: 2025-12-01T15:48:05.095Z

Learnt from: jlowin
Repo: jlowin/fastmcp PR: 0
File: :0-0
Timestamp: 2025-12-01T15:48:05.095Z
Learning: PR #2505 in fastmcp adds NEW functionality to get_access_token(): it now first checks request.scope["user"] for the token (which never existed before), then falls back to _sdk_get_access_token() (the only thing the original code did). This is not a reversal of order but entirely new functionality to fix stale token issues.

Applied to files:

docs/servers/auth/authorization.mdx
src/fastmcp/server/server.py
src/fastmcp/server/auth/authorization.py

📚 Learning: 2025-11-26T21:52:08.947Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-11-26T21:52:08.947Z
Learning: Applies to docs/**/*.mdx : Provide authentication examples showing proper format in MDX API documentation

Applied to files:

docs/servers/auth/authorization.mdx

📚 Learning: 2026-01-12T16:24:54.978Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:54.978Z
Learning: Applies to src/tools/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Tools (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

Applied to files:

src/fastmcp/tools/tool.py

📚 Learning: 2026-01-12T16:25:10.972Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-12T16:25:10.972Z
Learning: Applies to src/**/__init__.py : Be intentional about re-exports - don't blindly re-export everything to parent namespaces; only re-export fundamental types to fastmcp.*

Applied to files:

src/fastmcp/server/auth/__init__.py

🧬 Code graph analysis (6)

src/fastmcp/server/middleware/__init__.py (1)

src/fastmcp/server/middleware/authorization.py (1)

AuthMiddleware (48-144)

src/fastmcp/server/middleware/authorization.py (6)

src/fastmcp/server/auth/authorization.py (2)

AuthContext (45-57)

run_auth_checks (134-177)

src/fastmcp/server/dependencies.py (1)

get_access_token (375-426)

src/fastmcp/server/middleware/middleware.py (3)

CallNext (42-43)

Middleware (79-205)

MiddlewareContext (47-63)

src/fastmcp/server/providers/local_provider.py (4)

tool (350-367)

tool (370-387)

tool (393-542)

get_tool (266-269)

src/fastmcp/server/server.py (5)

tool (1772-1787)

tool (1790-1805)

tool (1807-1892)

name (427-428)

get_tool (890-923)

src/fastmcp/tools/tool.py (6)

tool (793-793)

tool (797-809)

tool (813-826)

tool (829-967)

Tool (148-408)

ToolResult (87-145)

src/fastmcp/server/providers/local_provider.py (3)

src/fastmcp/server/context.py (1)

fastmcp (186-191)

src/fastmcp/server/server.py (3)

tool (1772-1787)

tool (1790-1805)

tool (1807-1892)

src/fastmcp/tools/tool.py (6)

tool (793-793)

tool (797-809)

tool (813-826)

tool (829-967)

FunctionTool (411-560)

Tool (148-408)

src/fastmcp/server/server.py (5)

src/fastmcp/server/context.py (1)

fastmcp (186-191)

src/fastmcp/server/auth/authorization.py (2)

AuthContext (45-57)

run_auth_checks (134-177)

src/fastmcp/server/dependencies.py (1)

get_access_token (375-426)

src/fastmcp/tools/tool.py (7)

tool (793-793)

tool (797-809)

tool (813-826)

tool (829-967)

FunctionTool (411-560)

Tool (148-408)

ToolResult (87-145)

src/fastmcp/server/providers/base.py (1)

_is_component_enabled (331-342)

src/fastmcp/server/auth/__init__.py (1)

src/fastmcp/server/auth/authorization.py (5)

AuthContext (45-57)

require_auth (64-75)

require_scopes (78-103)

restrict_tag (106-131)

run_auth_checks (134-177)

src/fastmcp/server/auth/authorization.py (5)

src/fastmcp/exceptions.py (1)

AuthorizationError (42-43)

src/fastmcp/server/auth/auth.py (1)

AccessToken (43-46)

src/fastmcp/server/providers/local_provider.py (3)

tool (350-367)

tool (370-387)

tool (393-542)

src/fastmcp/server/server.py (3)

tool (1772-1787)

tool (1790-1805)

tool (1807-1892)

src/fastmcp/tools/tool.py (5)

tool (793-793)

tool (797-809)

tool (813-826)

tool (829-967)

Tool (148-408)

🪛 GitHub Actions: Run static analysis

src/fastmcp/server/providers/local_provider.py

[error] 1-1: Pre-commit loq: file size limit exceeded (743 > 738).

src/fastmcp/tools/tool.py

[error] 1-1: Pre-commit loq: file size limit exceeded (967 > 950).

src/fastmcp/server/server.py

[error] 1-1: Pre-commit loq: file size limit exceeded (2713 > 2682).

src/fastmcp/server/auth/authorization.py

[error] ruff-format made changes to files during pre-commit; please re-run formatting checks.

src/fastmcp/tools/tool_transform.py

[error] 1-1: Pre-commit loq: file size limit exceeded (953 > 952).

🪛 Ruff (0.14.10)

src/fastmcp/server/middleware/authorization.py

130-132: Avoid specifying long messages outside the exception class

(TRY003)

140-142: Avoid specifying long messages outside the exception class

(TRY003)

src/fastmcp/server/auth/authorization.py

168-168: Do not catch blind exception: Exception

(BLE001)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

GitHub Check: Run tests: Python 3.13 on ubuntu-latest
GitHub Check: Run tests: Python 3.10 on ubuntu-latest
GitHub Check: Run tests: Python 3.10 on windows-latest
GitHub Check: Run tests with lowest-direct dependencies

🔇 Additional comments (26)

src/fastmcp/tools/tool_transform.py (1)

597-597: Auth propagation looks correct.

The auth attribute is properly inherited from the parent tool. This ensures transformed tools maintain the same authorization requirements as their parent.

Consider whether auth should be an optional parameter in from_tool() to allow overriding the parent's auth (similar to annotations, tags, etc.), but the current inheritance-only behavior is reasonable for this initial implementation.

src/fastmcp/exceptions.py (1)

40-43: LGTM!

The new AuthorizationError class follows the established exception hierarchy pattern, properly inheriting from FastMCPError with a clear docstring.

src/fastmcp/server/middleware/__init__.py (1)

1-15: LGTM!

The AuthMiddleware is properly imported and exported, following the existing pattern for middleware components. The __all__ list is alphabetically ordered.

src/fastmcp/server/auth/__init__.py (1)

8-15: LGTM!

The authorization primitives are appropriately re-exported as they are fundamental types intended for public use. The exports include:

Core types (AuthCheck, AuthContext)

Built-in checks (require_auth, require_scopes, restrict_tag)

Utility function (run_auth_checks)

The __all__ list maintains alphabetical ordering. Based on learnings, these are intentional re-exports of fundamental types.

Also applies to: 22-39

docs/servers/auth/authorization.mdx (1)

1-382: Documentation is comprehensive and well-structured.

The authorization documentation follows the coding guidelines effectively:

Complete runnable code examples with realistic patterns

Clear progression from basic concepts to advanced topics

Proper use of Note, Warning, and tables for reference

Good coverage of exception handling patterns

Clear distinction between tool-level visibility and middleware enforcement

src/fastmcp/server/middleware/authorization.py (2)

83-106: LGTM! Proper tool filtering with STDIO bypass.

The on_list_tools implementation correctly:

Calls downstream first to get all tools

Bypasses filtering for STDIO transport

Evaluates auth checks for each tool individually

Returns only authorized tools

108-144: Solid fail-closed enforcement with appropriate error handling.

The on_call_tool implementation:

Correctly bypasses auth for STDIO transport

Fails closed when context is missing (good security posture)

Retrieves the tool and enforces middleware-level auth checks

Note: get_tool at line 134 may also run tool-level auth checks (per server.py lines 889-922), but this is intentional—tool-level auth and middleware-level auth are separate concerns that stack appropriately.

The static analysis hints about TRY003 (long exception messages) are acceptable here since the messages provide useful context for debugging authorization failures.

src/fastmcp/server/providers/local_provider.py (3)

44-44: LGTM!

Import correctly updated to include AuthCheckCallable for type annotations.

349-409: Auth parameter correctly added to all overloads and implementation.

The auth parameter is consistently added to:

First overload (line 366) for direct function decoration

Second overload (line 386) for parameterized decoration

Main implementation (line 409)

Type annotation AuthCheckCallable | list[AuthCheckCallable] | None matches the definition in tool.py.

489-508: LGTM! Auth correctly propagated in both decoration paths.

Line 502: auth=auth passed to Tool.from_function for immediate registration

Line 541: auth=auth included in partial for deferred decoration

Both paths correctly propagate the auth configuration.

Also applies to: 527-542

src/fastmcp/server/auth/authorization.py (5)

1-42: LGTM: Well-structured module with clear documentation.

The module docstring clearly explains the authorization semantics including how different exception types are handled. Imports are appropriate and the TYPE_CHECKING guard avoids circular imports correctly.

44-61: LGTM: Clean dataclass and type alias definitions.

AuthContext provides appropriate context for auth checks, and the AuthCheck type alias clearly defines the callable contract.

64-103: LGTM: Auth check implementations are correct.

Both require_auth and require_scopes correctly handle the None token case and implement the expected AND semantics for multiple scopes.

106-131: LGTM: Tag-based scope restriction logic is sound.

The restrict_tag function correctly allows access when the tag is absent and enforces scope requirements only when the tag is present on the tool.

165-175: The broad Exception catch is appropriate here for security.

Ruff flags BLE001 on line 168, but this is an intentional security pattern. Masking unexpected exceptions prevents information leakage about internal implementation details. The AuthorizationError is explicitly allowed to propagate, while other exceptions are logged and treated as denial. This follows security best practices for auth code.

src/fastmcp/tools/tool.py (7)

54-56: LGTM: Type alias appropriately uses Any to avoid circular imports.

The comment clearly explains why Any is used instead of the actual AuthContext type. This is a pragmatic solution for the circular import issue.

173-176: LGTM: Auth field properly added to Tool model.

The field accepts single callable, list of callables, or None, aligning with the flexible auth check API.

226-243: LGTM: Auth parameter correctly propagated in Tool.from_function.

The parameter is passed through to FunctionTool.from_function maintaining consistency.

451-515: LGTM: Auth propagation complete in FunctionTool.from_function.

The auth parameter is correctly passed to the cls() constructor, completing the propagation chain.

796-841: LGTM: Standalone @tool decorator overloads include auth parameter.

All three overload signatures consistently include the auth parameter with the correct type.

924-936: LGTM: Auth passed through in direct function decoration path.

955-967: LGTM: Auth included in partial return for deferred decoration.

The auth parameter is correctly included in the partial call for cases where the function isn't immediately available.

src/fastmcp/server/server.py (4)

71-72: LGTM: Auth-related imports added.

The imports bring in the necessary authorization infrastructure from the new auth module.

901-923: Auth check in get_tool mirrors get_tools correctly.

The STDIO bypass and auth check logic is consistent with get_tools. When auth fails, the loop continues to the next provider, ultimately raising NotFoundError if no authorized tool is found—this prevents leaking that the tool exists but is unauthorized.

1771-1826: LGTM: @server.tool decorator overloads include auth parameter.

Both overloads consistently include the auth: AuthCheckCallable | list[AuthCheckCallable] | None parameter.

1876-1892: LGTM: Auth correctly delegated to LocalProvider.

The auth parameter is properly passed through to self._local_provider.tool(), ensuring the authorization configuration reaches the tool registration.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a17a4142d8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-01-12T22:06:27Z

+                # Check tool-level auth (skip for STDIO)
+                if not is_stdio and tool.auth is not None:
+                    ctx = AuthContext(token=token, tool=tool)
+                    if not run_auth_checks(tool.auth, ctx):


Treat auth check errors as list_tools denials

run_auth_checks can raise AuthorizationError (the new docs even recommend it for explicit denials), but this call in get_tools does not catch it. That means a single tool with an auth check that raises will cause list_tools to fail for the entire request instead of simply hiding that tool, which breaks discovery for otherwise-authorized clients. Consider catching AuthorizationError here (and treating it as a failed check) so list_tools still returns the rest of the tools.

Useful? React with 👍 / 👎.

- AuthContext now uses `component` field instead of `tool` (tool is a backwards-compatible property) - Add `auth` parameter to all resource/prompt decorators - Add auth filtering to get_resources, get_prompts, etc. - AuthMiddleware now handles all component types - Catch AuthorizationError in list operations (hide instead of fail)

marvin-context-protocol · 2026-01-12T22:57:22Z

Test Failure Analysis

Summary: Static analysis failed because 9 files now exceed their configured line limits in loq.toml after adding authorization checks.

Root Cause: The PR adds authorization functionality to tools, resources, prompts, and the server, increasing file sizes. The loq pre-commit hook enforces file size limits to prevent files from growing too large. Several files now exceed their configured maximums.

Suggested Solution: Update loq.toml with the new line counts by running:

uv run loq baseline

This will automatically update all the line limits in loq.toml to match the current file sizes. Then commit the updated loq.toml file.

Detailed Analysis

The loq hook reported these violations:

✖    953 > 952    src/fastmcp/tools/tool_transform.py
✖    573 > 565    src/fastmcp/resources/template.py
✖    640 > 627    src/fastmcp/resources/resource.py
✖    751 > 738    src/fastmcp/server/providers/local_provider.py
✖    793 > 779    src/fastmcp/prompts/prompt.py
✖    967 > 950    src/fastmcp/tools/tool.py
✖  2_280 > 2_228  docs/changelog.mdx
✖    604 > 500    tests/server/auth/test_authorization.py (new file)
✖  2_811 > 2_682  src/fastmcp/server/server.py

Each file exceeded its limit by a small amount (1-129 lines), which is expected when adding a new cross-cutting feature like authorization. The loq baseline command will update the baseline limits to the current sizes.

Related Files

loq.toml - File size configuration that needs updating
.pre-commit-config.yaml - Configures the loq hook that enforces these limits

marvin-context-protocol · 2026-01-12T23:02:46Z

Test Failure Analysis

Summary: 5 tests failed - 4 OAuth client tests and 1 logging middleware test.

Root Cause:

OAuth Tests (4 failures): The dependency resolver is converting SDK objects to FastMCP's subclass, but the conversion is failing with a type mismatch error. The error message "Expected fastmcp.server.auth.auth.AccessToken, got AccessToken" suggests the type check at line 404 in dependencies.py is not correctly identifying SDK AccessToken instances.
Logging Test (1 failure): The ResourceTemplate now includes an auth field (line 118-120 in template.py), which is being serialized in the logging middleware output. The test snapshot expects the old serialization without the auth field.

Suggested Solution:

Fix 1: OAuth Type Check Issue (src/fastmcp/server/dependencies.py:404)

The problem is likely with the type check. The current code:

if access_token is None or isinstance(access_token, AccessToken):
    return access_token

This check should pass for SDK AccessToken objects (which FastMCP's AccessToken inherits from), but it seems to be failing. The issue might be that:

The SDK's _SDKAccessToken import or the inheritance chain is broken
There's a module reload/import issue causing type identity problems

Recommended fix: Update the type check to be more lenient:

# At line 404 in src/fastmcp/server/dependencies.py
if access_token is None:
    return access_token

# Check if it's already our AccessToken type
if isinstance(access_token, AccessToken):
    return access_token

# Check if it's at least an SDK AccessToken (duck typing check)
if hasattr(access_token, 'token') and hasattr(access_token, 'client_id') and hasattr(access_token, 'scopes'):
    # SDK AccessToken or compatible - proceed with conversion
    try:
        access_token_as_dict = access_token.model_dump()
        return AccessToken(
            token=access_token_as_dict["token"],
            client_id=access_token_as_dict["client_id"],
            scopes=access_token_as_dict["scopes"],
            expires_at=access_token_as_dict.get("expires_at"),
            resource=access_token_as_dict.get("resource"),
            claims=access_token_as_dict.get("claims", {}),
        )
    except Exception as e:
        raise TypeError(
            f"Expected AccessToken-like object, got {type(access_token).__name__}. "
            "Ensure the SDK is using the correct AccessToken type."
        ) from e

raise TypeError(f"Unexpected access_token type: {type(access_token).__name__}")

Fix 2: Logging Test Snapshot (tests/server/middleware/test_logging.py:335)

Update the expected snapshot to include the new auth field:

# At line 335 in tests/server/middleware/test_logging.py
'{\name\:\tmpl\,\title\:null,\description\:null,\icons\:null,\tags\:[],\meta\:null,\task_config\:{\mode\:\forbidden\,\poll_interval\:\PT5S\},\uri_template\:\tmpl://{id}\,\mime_type\:\text/plain\,\parameters\:{\id\:{\type\:\string\}},\annotations\:null,\auth\:null}"

The snapshot now needs to include ,\auth\:null at the end before the closing brace.

Detailed Analysis

OAuth Test Failures

All 4 OAuth tests are failing with the same error pattern:

Expected fastmcp.server.auth.auth.AccessToken, got AccessToken

This occurs in src/fastmcp/server/dependencies.py:424 within the get_access_token() function. The function attempts to convert SDK AccessToken objects to FastMCP's AccessToken subclass, but the conversion logic is throwing a TypeError.

The failing tests are:

test_list_tools (test_oauth_client.py:79)
test_call_tool (test_oauth_client.py:87)
test_list_resources (test_oauth_client.py:96)
test_read_resource (test_oauth_client.py:104)

Logging Test Failure

The test_on_message_with_resource_template_in_payload test is comparing serialized JSON output and expects specific fields. The new auth field was added to ResourceTemplate in this PR, which changed the serialization output.

Related Files

Primary files requiring changes:

src/fastmcp/server/dependencies.py:404-426 - Type check and conversion logic for AccessToken
tests/server/middleware/test_logging.py:335 - Test snapshot expecting serialized ResourceTemplate

Related to the issue:

src/fastmcp/server/auth/auth.py:43-46 - FastMCP's AccessToken class definition
src/fastmcp/resources/template.py:118-120 - New auth field on ResourceTemplate
src/fastmcp/prompts/prompt.py:204-206 - New auth field on Prompt (similar change)
src/fastmcp/tools/tool.py - Likely has similar auth field addition

marvin-context-protocol · 2026-01-12T23:03:19Z

Test Failure Analysis

Summary: 5 tests failed - 4 OAuth client tests and 1 logging middleware test.

Root Cause:

OAuth Tests (4 failures): The get_access_token() dependency resolver is converting SDK AccessToken objects to FastMCP's AccessToken subclass, but the conversion is failing with a type mismatch error. The error message "Expected fastmcp.server.auth.auth.AccessToken, got AccessToken" suggests the type check at line 404 in dependencies.py is not correctly identifying SDK AccessToken instances.
Logging Test (1 failure): The ResourceTemplate now includes an auth field (line 118-120 in template.py), which is being serialized in the logging middleware output. The test snapshot expects the old serialization without the auth field.

Suggested Solution:

Fix 1: OAuth Type Check Issue

File: src/fastmcp/server/dependencies.py:404-426

The problem is with the type check at line 404. The current code has an isinstance() check that should pass for SDK AccessToken objects, but it's failing. This might be due to module reloading or import issues causing type identity problems.

Recommended approach: Add duck typing fallback to handle SDK AccessToken objects more gracefully. Instead of relying solely on isinstance(), check for the presence of required attributes and attempt the conversion for any AccessToken-like object.

The key change needed: Restructure the conditional logic to first check for None, then for FastMCP AccessToken, then attempt conversion for any object with the required AccessToken attributes. The existing try/except should catch any actual incompatibilities.

Fix 2: Logging Test Snapshot

File: tests/server/middleware/test_logging.py:335

Update the expected snapshot to include the new auth field. The serialized JSON now includes "auth":null at the end.

Detailed Analysis

OAuth Test Failures

All 4 OAuth tests are failing with the same error pattern:

Expected fastmcp.server.auth.auth.AccessToken, got AccessToken

This occurs in src/fastmcp/server/dependencies.py:424 within the get_access_token() function. The function attempts to convert SDK AccessToken objects to FastMCP's AccessToken subclass, but the conversion logic is throwing a TypeError.

The failing tests are:

test_list_tools (test_oauth_client.py:79)
test_call_tool (test_oauth_client.py:87)
test_list_resources (test_oauth_client.py:96)
test_read_resource (test_oauth_client.py:104)

All tests use the client_with_headless_oauth fixture which performs OAuth authentication. The failure happens when the server tries to process requests with the authenticated token.

Logging Test Failure

The test_on_message_with_resource_template_in_payload test compares serialized JSON output. The test creates a ResourceTemplate and logs it via StructuredLoggingMiddleware with include_payloads=True.

The test expects the old serialization without the auth field, but now the auth field is included in the output.

Related Files

Primary files requiring changes:

src/fastmcp/server/dependencies.py:404-426 - Type check and conversion logic for AccessToken
tests/server/middleware/test_logging.py:335 - Test snapshot expecting serialized ResourceTemplate

Related to the issue:

src/fastmcp/server/auth/auth.py:43-46 - FastMCP's AccessToken class definition
src/fastmcp/resources/template.py:118-120 - New auth field on ResourceTemplate
src/fastmcp/prompts/prompt.py:204-206 - New auth field on Prompt (similar change)
src/fastmcp/tools/tool.py - Likely has similar auth field addition

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/fastmcp/resources/template.py (1)
447-573: Propagate template auth to ephemeral Resource in create_resource().

The template's auth field is currently not passed to Resource.from_function() when creating the ephemeral resource. Since Resource.from_function() accepts the auth parameter, it should be propagated to ensure the authorization policy is maintained if downstream code evaluates the Resource directly instead of the template.
Fix
diff --git a/src/fastmcp/resources/template.py b/src/fastmcp/resources/template.py
@@
     async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
         """Create a resource from the template with the given parameters."""
 
         async def resource_read_fn() -> str | bytes | ResourceResult:
             # Call function and check if result is a coroutine
             result = await self.read(arguments=params)
             return result
 
         return Resource.from_function(
             fn=resource_read_fn,
             uri=uri,
             name=self.name,
             description=self.description,
             mime_type=self.mime_type,
             tags=self.tags,
             task=self.task_config,
+            auth=self.auth,
         )

🧹 Nitpick comments (3)

src/fastmcp/prompts/prompt.py (1)

636-793: Good: standalone prompt(...) decorator overloads + implementation consistently accept/propagate auth.

Minor: this file now has multiple “auth union” spellings (field vs overloads). If you find yourself repeating this elsewhere, a local type PromptAuth = ... alias can help.

src/fastmcp/resources/resource.py (1)

36-37: Same coupling note as prompts: importing auth typing from fastmcp.tools.tool—confirm that’s intentional.

src/fastmcp/server/server.py (1)

864-871: Refactor duplicated auth-check pattern into a helper function.

The pattern of checking is_stdio = _current_transport.get() == "stdio" followed by token = None if is_stdio else get_access_token() is duplicated across 8 methods in server.py and multiple methods in middleware/authorization.py. Extract this into a small internal helper to reduce duplication and make future changes easier to propagate.

Note: The ContextVar _current_transport is defined with default=None, so calling .get() is safe and will not raise LookupError.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a17a414 and 030e719.

⛔ Files ignored due to path filters (1)

tests/server/auth/test_authorization.py is excluded by none and included by none

📒 Files selected for processing (7)

src/fastmcp/prompts/prompt.py
src/fastmcp/resources/resource.py
src/fastmcp/resources/template.py
src/fastmcp/server/auth/authorization.py
src/fastmcp/server/middleware/authorization.py
src/fastmcp/server/providers/local_provider.py
src/fastmcp/server/server.py

🧰 Additional context used

📓 Path-based instructions (1)

src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.py: Python source code must use Python ≥3.10 with full type annotations
Never use bare except - be specific with exception types
Prioritize readable, understandable code - clarity over cleverness; avoid obfuscated or confusing patterns
Follow existing patterns and maintain consistency across the codebase

Files:

src/fastmcp/resources/template.py
src/fastmcp/server/server.py
src/fastmcp/server/providers/local_provider.py
src/fastmcp/server/auth/authorization.py
src/fastmcp/resources/resource.py
src/fastmcp/prompts/prompt.py
src/fastmcp/server/middleware/authorization.py

🧠 Learnings (3)

📓 Common learnings

Learnt from: jlowin
Repo: jlowin/fastmcp PR: 0
File: :0-0
Timestamp: 2025-12-01T15:48:05.095Z
Learning: PR #2505 in fastmcp adds NEW functionality to get_access_token(): it now first checks request.scope["user"] for the token (which never existed before), then falls back to _sdk_get_access_token() (the only thing the original code did). This is not a reversal of order but entirely new functionality to fix stale token issues.

📚 Learning: 2025-12-01T15:48:05.095Z

Learnt from: jlowin
Repo: jlowin/fastmcp PR: 0
File: :0-0
Timestamp: 2025-12-01T15:48:05.095Z
Learning: PR #2505 in fastmcp adds NEW functionality to get_access_token(): it now first checks request.scope["user"] for the token (which never existed before), then falls back to _sdk_get_access_token() (the only thing the original code did). This is not a reversal of order but entirely new functionality to fix stale token issues.

Applied to files:

src/fastmcp/server/server.py
src/fastmcp/server/auth/authorization.py

📚 Learning: 2026-01-12T16:24:54.978Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:54.978Z
Learning: Applies to src/prompts/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Prompts (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

Applied to files:

src/fastmcp/prompts/prompt.py

🧬 Code graph analysis (4)

src/fastmcp/resources/template.py (3)

src/fastmcp/server/providers/local_provider.py (3)

tool (350-367)

tool (370-387)

tool (393-542)

src/fastmcp/server/server.py (3)

tool (1864-1879)

tool (1882-1897)

tool (1899-1984)

src/fastmcp/tools/tool.py (4)

tool (793-793)

tool (797-809)

tool (813-826)

tool (829-967)

src/fastmcp/server/auth/authorization.py (5)

src/fastmcp/exceptions.py (1)

AuthorizationError (42-43)

src/fastmcp/server/auth/auth.py (1)

AccessToken (43-46)

src/fastmcp/server/providers/local_provider.py (3)

tool (350-367)

tool (370-387)

tool (393-542)

src/fastmcp/tools/tool.py (5)

tool (793-793)

tool (797-809)

tool (813-826)

tool (829-967)

Tool (148-408)

src/fastmcp/utilities/components.py (1)

FastMCPComponent (34-184)

src/fastmcp/resources/resource.py (3)

src/fastmcp/server/auth/authorization.py (1)

tool (63-70)

src/fastmcp/server/providers/local_provider.py (3)

tool (350-367)

tool (370-387)

tool (393-542)

src/fastmcp/server/server.py (3)

tool (1864-1879)

tool (1882-1897)

tool (1899-1984)

src/fastmcp/prompts/prompt.py (4)

src/fastmcp/server/auth/authorization.py (1)

tool (63-70)

src/fastmcp/server/providers/local_provider.py (3)

tool (350-367)

tool (370-387)

tool (393-542)

src/fastmcp/server/server.py (3)

tool (1864-1879)

tool (1882-1897)

tool (1899-1984)

src/fastmcp/tools/tool.py (4)

tool (793-793)

tool (797-809)

tool (813-826)

tool (829-967)

🪛 GitHub Actions: Run static analysis

src/fastmcp/resources/template.py