Route vs. Global Dependency Application

1. Understanding Dependency Scopes in FastAPI

Before we apply this to fastapi-mcp, it's essential to understand how FastAPI handles dependency scopes natively. A dependency can be applied at three main levels: the individual path operation, a router (a group of paths), or the entire application.

To get a solid overview of these scopes, please read the following article. It provides clear explanations and code examples for each level.

As a supplement, the following video offers a visual demonstration of applying dependencies at the path operation and global levels.

2. Scopes in the Context of fastapi-mcp

Now, let's translate this general FastAPI knowledge into our specific fastapi-mcp project. We have two primary ways to apply our pre-hooks:

A. Route-Specific Dependencies (For a Single Tool)

This is what we've been doing in the last two lessons. You apply a dependency directly to the FastAPI route that corresponds to your tool.

• How:

  1. Function Signature (our current method): Using Annotated to inject the dependency and access its return value. This is ideal for validation that also transforms or passes data through.

     async def cancel_order(order_id: Annotated[str, Depends(ensure_order_is_cancellable)]):
         ...
     

  2. Path Operation Decorator: Using the dependencies parameter in the decorator. This is best for "fire-and-forget" checks that don't need to return a value to the endpoint, like logging or simple permission checks.

     @app.post(
         "/orders/{order_id}/cancel",
         dependencies=[Depends(ensure_order_is_cancellable)],
         ...
     )
     async def cancel_order(order_id: str):
         ...
     

• When to Use: Use this for logic that is unique to a single tool. Our ensure_order_is_cancellable dependency is a perfect example. It makes no sense to check if a customer profile is "cancellable," so this dependency belongs only to the cancel_order tool.

B. Global Dependencies (For All Tools in an MCP Server)

This is for applying logic across an entire toolset. Instead of adding a dependency to every single route, fastapi-mcp lets you define it once in the AuthConfig.

You've already done this! The verify_auth dependency is a global dependency. It runs for every tool exposed by your MCP instance, ensuring no tool can be executed without a valid token.

To understand how fastapi-mcp handles this, let's look at its documentation.

• How: By passing a list of Depends objects to the dependencies parameter of AuthConfig when you instantiate FastApiMCP.

  mcp = FastApiMCP(
      app,
  
  
  
      # ...
      auth_config=AuthConfig(
          dependencies=[Depends(verify_auth)], # This applies to all tools
      ),
  )
  

• When to Use: Use this for cross-cutting concerns that must apply to every tool call. Good examples include:

  • Authentication: Is the user logged in? (Our verify_auth does this).
  • Authorization: Does the user have the basic role needed to use tools at all?
  • Logging: Recording every tool execution for auditing.
  • Billing/Rate-Limiting: Checking if the user has exceeded their API call quota.

3. Practical Exercise: Adding a Global Logging Dependency

Let's demonstrate the power of a global dependency by adding a simple logger that prints a message to your console every time any tool is called.

1. Create the Logging Dependency

In main.py, add a new, simple dependency function. It doesn't need to be async as it performs no I/O.

# main.py




# ... add this near your other dependencies

def log_tool_call(request: Request):
    """A simple dependency that logs which tool path was called."""
    print(f"--- Tool call received for: {request.url.path} ---")

Note: We add request: Request as a parameter so FastAPI will pass the request object into our function, giving us access to useful information like the URL.

2. Apply it Globally

Now, modify your FastApiMCP instance to include this new dependency. It will run alongside verify_auth. FastAPI executes dependencies in the order they are listed.

# main.py




# ... update your FastApiMCP instance

mcp = FastApiMCP(
    app,
    name="Apxml API Services",
    description="Tools for managing orders and customers.",
    describe_all_responses=True,
    describe_full_response_schema=True,
    include_operations=[
        "get_order_details",
        "get_customer_profile",
        "cancel_order",
    ],
    auth_config=AuthConfig(
        dependencies=[
            Depends(verify_auth), 
            Depends(log_tool_call) # Add the new dependency here
        ],
    ),
)

3. Verify the Global Application

1. Ensure your server is running (uv run uvicorn main:app --reload).
2. Open the MCP Inspector, connect, and add your Authorization header.
3. Execute the get_order_details tool with order_id: ORD12345.
   • Check your terminal. You should see: --- Tool call received for: /orders/ORD12345 ---
4. Now, execute the get_customer_profile tool with customer_id: 101.
   • Check your terminal again. You should see: --- Tool call received for: /customers/101 ---
5. Finally, execute cancel_order with order_id: ORD999.
   • And again, in the terminal: --- Tool call received for: /orders/ORD999/cancel ---

As you can see, the log_tool_call dependency was executed for every tool without you having to add it to each endpoint individually.

Conclusion

In this lesson, you've learned the critical difference between applying dependencies at a route-specific versus a global scope within your fastapi-mcp server. This distinction is fundamental to building clean, secure, and maintainable AI toolsets.

Key Takeaways:

Choosing the right scope is an architectural decision. By correctly placing your validation and gating logic, you avoid repeating code and ensure that security checks are never accidentally forgotten.

Next Up: We have now completed our deep dive into pre-tool hooks. In the next module, we'll shift our focus to the other side of the tool call: post-tool patterns. You'll learn how to modify a tool's response before it goes to the model and, most excitingly, how to manage state between tool calls—a concept that directly mirrors the "slot setting" you're familiar with from Rasa.