π The fast, Pythonic way to build MCP servers and clients.
Upgrade Eunomia authorization docs (#1144)
tommitt13dd2bfa0ccc
diff --git a/docs/integrations/eunomia-authorization.mdx b/docs/integrations/eunomia-authorization.mdxindex e18ff0779..e69607006 100644--- a/docs/integrations/eunomia-authorization.mdx+++ b/docs/integrations/eunomia-authorization.mdx@@ -6,13 +6,36 @@ icon: shield-checktag: NEW----Add **policy-based authorization** to your FastMCP servers with minimal code changes using Eunomia authorization middleware.+Add **policy-based authorization** to your FastMCP servers with one-line code addition with the **[Eunomia][eunomia-github] authorization middleware**.-Control which actions MCP clients can perform on your server by restricting how the agent can access resources, tools and prompts by using JSON-based policies, while obtaining a comprehensive audit log of all access attempts and violations.+Control which tools, resources and prompts MCP clients can view and execute on your server. Define dynamic JSON-based policies and obtain a comprehensive audit log of all access attempts and violations.-## Eunomia Authorization Middleware+## How it Works-The middleware intercepts all MCP requests to your server and automatically maps MCP methods to authorization checks.+Exploiting FastMCP's [Middleware][fastmcp-middleare], the Eunomia middleware intercepts all MCP requests to your server and, then, automatically maps MCP methods to authorization checks.++### Listing Operations++The middleware behaves as a filter for listing operations (`tools/list`, `resources/list`, `prompts/list`), hiding to the client components that are not authorized by the defined policies.++```mermaid+sequenceDiagram+ participant MCPClient as MCP Client+ participant EunomiaMiddleware as Eunomia Middleware+ participant MCPServer as FastMCP Server+ participant EunomiaServer as Eunomia Server++ MCPClient->>EunomiaMiddleware: MCP Listing Request (e.g., tools/list)+ EunomiaMiddleware->>MCPServer: MCP Listing Request+ MCPServer-->>EunomiaMiddleware: MCP Listing Response+ EunomiaMiddleware->>EunomiaServer: Authorization Checks+ EunomiaServer->>EunomiaMiddleware: Authorization Decisions+ EunomiaMiddleware-->>MCPClient: Filtered MCP Listing Response+```++### Execution Operations++The middleware behaves as a firewall for execution operations (`tools/call`, `resources/read`, `prompts/get`), blocking operations that are not authorized by the defined policies.```mermaidsequenceDiagram@@ -21,15 +44,17 @@ sequenceDiagramparticipant MCPServer as FastMCP Serverparticipant EunomiaServer as Eunomia Server- MCPClient->>EunomiaMiddleware: MCP Request- Note over MCPClient, EunomiaMiddleware: Middleware intercepts request to server+ MCPClient->>EunomiaMiddleware: MCP Execution Request (e.g., tools/call)EunomiaMiddleware->>EunomiaServer: Authorization Check- EunomiaServer->>EunomiaMiddleware: Authorization Decision (allow/deny)+ EunomiaServer->>EunomiaMiddleware: Authorization DecisionEunomiaMiddleware-->>MCPClient: MCP Unauthorized Error (if denied)- EunomiaMiddleware->>MCPServer: MCP Request (if allowed)- MCPServer-->>MCPClient: MCP Response (if allowed)+ EunomiaMiddleware->>MCPServer: MCP Execution Request (if allowed)+ MCPServer-->>EunomiaMiddleware: MCP Execution Response (if allowed)+ EunomiaMiddleware-->>MCPClient: MCP Execution Response (if allowed)```+## Add Authorization to Your Server+<Note>Eunomia is an AI-specific standalone authorization server that handles policy decisions. You must have an Eunomia server running alongside your FastMCP server for the middleware to function.@@ -49,11 +74,11 @@ First, install the `eunomia-mcp` package:pip install eunomia-mcp```-Then create a FastMCP server and add the Eunomia middleware with a few lines of code:+Then create a FastMCP server and add the Eunomia middleware in one line:```python server.pyfrom fastmcp import FastMCP-from eunomia_mcp import create_eunomia_middleware+from eunomia_mcp import EunomiaMcpMiddlewaremcp = FastMCP("Secure FastMCP Server π")@@ -62,12 +87,11 @@ def add(a: int, b: int) -> int:"""Add two numbers"""return a + b-middleware = [create_eunomia_middleware()]-app = mcp.http_app(middleware=middleware)+middleware = EunomiaMcpMiddleware()+app = mcp.add_middleware(middleware)if __name__ == "__main__":- import uvicorn- uvicorn.run(app, host="0.0.0.0", port=8080)+ mcp.run()```### Configure Access Policies@@ -97,12 +121,14 @@ Start your FastMCP server normally:python server.py```-The middleware will now intercept all MCP requests and check them against your policies. Requests include agent identification through headers like `X-Agent-ID`, `X-User-ID`, or `Authorization` and an automatic mapping of MCP methods to authorization resources and actions.+The middleware will now intercept all MCP requests and check them against your policies. Requests include agent identification through headers like `X-Agent-ID`, `X-User-ID`, `User-Agent`, or `Authorization` and an automatic mapping of MCP methods to authorization resources and actions.<Tip>For detailed policy configuration, custom authentication, and advanceddeployment patterns, visit the [Eunomia MCP Middleware- repository][eunomia-github].+ repository][eunomia-mcp-github].</Tip>-[eunomia-github]: https://github.com/whataboutyou-ai/eunomia/tree/main/pkgs/extensions/mcp+[eunomia-github]: https://github.com/whataboutyou-ai/eunomia+[eunomia-mcp-github]: https://github.com/whataboutyou-ai/eunomia/tree/main/pkgs/extensions/mcp+[fastmcp-middleare]: /servers/middleware