README

OpenFGA MCP Server

Stop writing authorization logic. Start asking questions.

Manage and query your OpenFGA server using AI agents and tooling. Unlock the power of OpenFGA and Auth0 FGA inside agentic tooling and intelligent workflows.

Usage

Configure your MCP client to use the server's Docker image:

{
  "mcpServers": {
    "OpenFGA": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull=always",
        "-e",
        "OPENFGA_MCP_API_URL=http://host.docker.internal:8080",
        "evansims/openfga-mcp:latest"
      ]
    }
  }
}

The server should work with any MCP client, but has been tested with Visual Studio Code, Docker, Claude Desktop, Claude Code, Zed, Cursor, Windsurf, Warp and Raycast.

Configuration

The server supports the following configuration options:

Environment Variable	Default	Description
`OPENFGA_MCP_API_URL`	`http://127.0.0.1:8080`	URL of your OpenFGA server. Note: the Docker image defaults to `http://host.docker.internal:8080`
`OPENFGA_MCP_TRANSPORT`	`stdio`	Transport to use for communication with the MCP server (`stdio` or `http`)
`OPENFGA_MCP_TRANSPORT_HOST`	`127.0.0.1`	The host to bind the MCP server to (only affects HTTP transport)
`OPENFGA_MCP_TRANSPORT_PORT`	`8080`	The port to bind the MCP server to (only affects HTTP transport)
`OPENFGA_MCP_TRANSPORT_JSON`	`false`	Enables JSON responses (only affects HTTP transport)
`OPENFGA_MCP_API_READONLY`	`false`	Disable write operations (create, update, delete)
`OPENFGA_MCP_API_RESTRICT`	`false`	Restrict the MCP server to ONLY use the configured OPENFGA_MCP_API_STORE and/or OPENFGA_MCP_API_MODEL
`OPENFGA_MCP_API_STORE`	`null`	OpenFGA Store ID the MCP server should use by default
`OPENFGA_MCP_API_MODEL`	`null`	OpenFGA Model ID the MCP server should use by default

Authentication

By default, the server will try to connect to the OpenFGA server without using authentication.

To use pre-shared key (token) authentication, the server accepts the following configuration options:

Environment Variable	Default	Description
`OPENFGA_MCP_API_TOKEN`	`null`	API token for use with your OpenFGA server

To use Client Credentials authentication, the server accepts the following configuration options:

Environment Variable	Default	Description
`OPENFGA_MCP_API_CLIENT_ID`	`null`	Client ID for use with your OpenFGA server
`OPENFGA_MCP_API_CLIENT_SECRET`	`null`	Client secret for use with your OpenFGA server
`OPENFGA_MCP_API_ISSUER`	`null`	API issuer for use with your OpenFGA server
`OPENFGA_MCP_API_AUDIENCE`	`null`	API audience for use with your OpenFGA server

Features

Tools

Store Management

create_store: Creates a new store.
list_stores: List all stores.
get_store: Get a store's details by its ID.
delete_store: Delete a store by its ID.

Authorization Model Management

create_model: Use OpenFGA's DSL to create an authorization model.
list_models: List authorization models.
get_model: Get an authorization model's details by its ID.
verify_model: Verify a DSL representation of an authorization model.
get_model_dsl: Get the DSL from a specific authorization model from a particular store.

Relationship Tuples Management

check_permission: Check if something has a relation to an object. This answers, can (user) do (relation) on (object)?
grant_permission: Grant permission to something on an object by creating a relationship tuple.
revoke_permission: Revoke permission from something on an object by deleting a relationship tuple.
list_users: Return a list of users that have a given relationship with a given object.
list_objects: Return a list of objects of a type that something has a relation to.

Resources

openfga://stores: List all available OpenFGA stores.

Resource Templates

Store Templates

openfga://store/{storeId}: Get detailed information about a specific store.
openfga://store/{storeId}/models: List all authorization models in a store.

Model Templates

openfga://store/{storeId}/model/{modelId}: Get detailed information about a specific authorization model.
openfga://store/{storeId}/model/latest: Get the latest authorization model in a store.

Relationship Templates

openfga://store/{storeId}/users: List all users in a store (extracted from relationship tuples).
openfga://store/{storeId}/objects: List all objects in a store (extracted from relationship tuples).
openfga://store/{storeId}/relationships: List all relationship tuples in a store.
openfga://store/{storeId}/check?user={user}&relation={relation}&object={object}: Check if a user has a specific permission on an object.
openfga://store/{storeId}/expand?object={object}&relation={relation}: Expand all users who have a specific relation to an object.

Prompts

Authorization Model Design

design_model_for_domain: Generate guidance for designing OpenFGA authorization models for specific domains (e.g., document management, e-commerce, healthcare).
convert_rbac_to_rebac: Provide step-by-step guidance for converting traditional RBAC systems to OpenFGA's ReBAC patterns.
model_hierarchical_relationships: Help design complex hierarchical relationships and inheritance patterns.
optimize_model_structure: Analyze and optimize existing authorization models for performance and maintainability.

Relationship Troubleshooting

debug_permission_denial: Generate systematic debugging approaches for permission denials and access issues.
analyze_permission_inheritance: Provide analysis of permission inheritance paths and relationship chains.
troubleshoot_unexpected_access: Help investigate unexpected permission grants and security issues.
optimize_relationship_queries: Offer guidance for optimizing relationship query performance.

Security Guidance

security_review_model: Conduct comprehensive security reviews of authorization models for compliance.
implement_least_privilege: Provide guidance for implementing principle of least privilege in authorization design.
secure_delegation_patterns: Help design secure delegation patterns for temporary and permanent access.
audit_friendly_patterns: Generate audit-friendly authorization patterns for regulatory compliance.

Completion Providers

The server provides intelligent auto-completion suggestions for resource template parameters and prompt arguments. This helps MCP clients offer a better user experience by suggesting valid options as users type.

Dynamic Completion Providers

StoreIdCompletionProvider: Provides auto-completion for OpenFGA store IDs by fetching available stores from your OpenFGA server.
ModelIdCompletionProvider: Suggests model IDs from a specific store, including the 'latest' option for accessing the most recent model.
RelationCompletionProvider: Offers relation names extracted from authorization models (e.g., 'viewer', 'editor', 'owner').
UserCompletionProvider: Suggests user identifiers extracted from existing relationship tuples.
ObjectCompletionProvider: Provides object identifiers extracted from existing relationship tuples.

Static Completion Providers

The server also includes enum-based completion providers for common parameters:

Security & Compliance: Security levels (low, medium, high, critical), compliance frameworks (SOC2, HIPAA, PCI-DSS, GDPR), audit frequencies.
System Classification: System types (microservices, monolith, hybrid), criticality levels, access patterns.
Authorization Patterns: Delegation types (temporary, permanent, conditional), complexity levels, query types, risk levels.

Want to help? Get started with our contributors guide.
Licensed under the Apache 2.0 License.

evansims / openfga-mcp

Maintainers

Details