OpenFGA MCP Server

How to use

You interact with the OpenFGA MCP server through your MCP client. Start your MCP client configured for the openfga MCP server, then issue the available tool commands to list stores, read or deploy models, manage tuples, and perform permission checks. You can run single actions or batch operations to manage multiple tuples at once, and you can expand permission trees to understand access paths.

Typical usage flows include reading the current Authorization Model to verify its state, deploying an updated model, creating and updating tuples to reflect user permissions, and performing checks to confirm whether a user has a given permission on an object. You can also list objects accessible to a user, and expand a user’s permission tree to see all reachable objects.

How to install

Prerequisites: ensure you have Node.js and npm installed on your machine. You will install dependencies and compile the MCP server before running it.

# Install dependencies
npm install

# Build the MCP server
npm run build

Configuration and runtime notes

The server uses environment configuration to determine how to connect to your OpenFGA deployment. You can configure a local environment for development or set up a prod/staging configuration via a JSON environment map or individual environment variables.

# Claude Code project configuration (example)
{
  "mcpServers": {
    "openfga": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/openfga-mcp/dist/index.js"]
    }
  },
  "env": {
    "OPENFGA_ENVIRONMENTS": "{\"prod\":{\"url\":\"https://openfga.example.com\",\"defaultStoreId\":\"01ABC...\"}}"
  }
}

Security and environment examples

Use environment variables to control which OpenFGA instance you target. The following example shows a production environment entry using a JSON-based environment map.

# JSON-based environments (recommended)
export OPENFGA_ENVIRONMENTS='{
  "prod": {
    "url": "https://openfga.example.com",
    "defaultStoreId": "01ABC..."
  },
  "staging": {
    "url": "https://openfga-staging.example.com"
  }
}'

Additional local development setup

For local development, you can point the server to a local OpenFGA instance and provide a local store ID.

# Local defaults
export OPENFGA_LOCAL_URL="http://localhost:8080"
export OPENFGA_LOCAL_STORE_ID="01XYZ..."

Usage examples

Model read, model write, and checks are performed by dedicated tools. You can reference the available tool commands to perform operations like reading the model, deploying a new model, checking permissions, and managing tuples.

# Example tool invocations (these are illustrative commands you run through your MCP client)
openfga_model_read(env: "prod")
openfga_model_write(env: "prod", filePath: "/path/to/model.fga")
openfga_check(env: "prod", user: "user:alice", relation: "can_view", object: "document:1")
openfga_tuple_write(env: "prod", user: "user:alice", relation: "viewer", object: "document:1")
openfga_tuple_batch_write(env: "prod", tuples: [
  {user: "user:alice", relation: "viewer", object: "document:1"},
  {user: "user:bob", relation: "editor", object: "document:1"}
])

Hooks 연동 (선택)

If you want automated post-deploy actions, configure Claude Code Hooks to run scripts after model deployment or other tool uses.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "mcp__openfga__openfga_model_write",
      "hooks": [{
        "type": "command",
        "command": "./scripts/post-model-deploy.sh"
      }]
    }]
  }
}

개발 및 라이선스

개발 중에는 필요한 경우 빌드를 다시 실행하고 개발 모드로 실행해 변경 사항을 반영할 수 있습니다. 라이선스는 MIT입니다.

openfga_store_list

Retrieve the list of stores available in your OpenFGA deployment.

openfga_model_read

Read the current Authorization Model for a store.

openfga_model_write

Deploy an Authorization Model to a store (DSL file or string).

openfga_tuple_read

Query tuples with optional filters to inspect permissions.

openfga_tuple_write

Create a single tuple to establish a permission relation.

openfga_tuple_batch_write

Create multiple tuples in a batch to set up permissions efficiently.

openfga_tuple_delete

Delete a specific tuple from a store.

openfga_check

Check whether a user has a specific relation on an object.

openfga_list_objects

List objects that are accessible by a user.”

openfga_expand

Expand a user’s permission tree to reveal reachable objects.