permit-fastmcp

permit-fastmcp is a FastMCP middleware that adds Permit.io authorization to your MCP servers. It intercepts MCP requests and validates them against Permit.io policies before allowing access to tools and resources. The middleware supports policy mapping where MCP server methods like tools/list or resources/read are mapped to Permit.io resources and actions, and it also supports ABAC based on tool arguments to evaluate dynamic access conditions. To use it, install the package, create a FastMCP server, and attach PermitMcpMiddleware with your Permit.io PDP URL and API key. Once configured, you can define tools in your MCP server as usual; access will be gated according to the policies you configure in Permit.io. The middleware handles authentication context, so actions and resources you expose can be gated per user roles and the evaluated ABAC conditions. For JWT-based setups, ensure your authentication flow provides the expected identity to Permit.io for role checks and policy evaluation.

Prerequisites:

• Python 3.8+ and pip
• An MCP server runtime compatible with FastMCP (Python)
• A Permit.io account with a configured PDP URL and API key for authorization

Option A: Install via UV (recommended)

1. Ensure you have UV installed
2. Install the package: uv add permit-fastmcp

Option B: Install via pip

1. Install the package from PyPI: pip install permit-fastmcp

Option C: Verify installation

1. Create a quick FastMCP server and attach the middleware (see Quick Start in the README).
2. Run your server and ensure it binds to a transport (e.g., http) as demonstrated in the example.

Environment variables (required by middleware):

• PERMIT_API_KEY: your Permit.io API key
• PERMIT_PDP_URL: Permit.io PDP URL (e.g., http://localhost:7766)

Example quick-start (illustrative):

• Create a Python file (server.py) that initializes FastMCP and adds PermitMcpMiddleware with your PDP URL and API key, then run the server:

from fastmcp import FastMCP from permit_fastmcp.middleware.middleware import PermitMcpMiddleware

mcp = FastMCP("My MCP Server") mcp.add_middleware(PermitMcpMiddleware( permit_pdp_url="http://localhost:7766", permit_api_key="your-permit-api-key" ))

@mcp.tool def my_tool(data: str) -> str: return f"Processed: {data}"

if name == "main": mcp.run(transport="http")

Tips and considerations:

• Ensure that your Permit.io policies map correctly to MCP resource and action conventions used by the middleware (e.g., resources like {server_name}_{component} and actions like the HTTP method or tool name).
• For ABAC, the middleware flattens tool arguments into attributes (e.g., arg_name, arg_number). You can create policies that evaluate these attributes to allow or deny access.
• Remember to assign relevant roles (e.g., Admin, User) to the authenticating user in your Permit.io Directory so that policy decisions reflect the intended permissions.
• If JWT authentication is used, ensure the JWT contains the identity information required by your policies and that Permit.io can map it to the correct user/roles.
• When debugging, enable logging on both your MCP server and Permit.io integration to inspect which policies are being evaluated and which attributes are present.
• The provided example demonstrates a simple integration; adapt the server name, resources, and actions in your policy mapping to match your MCP server configuration.
• If you switch transport (e.g., from http to websockets), verify that the middleware and Permit.io configuration still align with your security requirements.