MCP Server (@auris/mcp)

@auris/mcp is the official Model Context Protocol  server for Auris IAM. It exposes 49 tools across nine domains — users, roles, organizations, applications, sessions, audit logs, webhooks, fine-grained authorization, and tenant configuration — so that any MCP-compatible AI agent can manage your identity layer through natural language.

The server communicates over stdio and is compatible with Claude Desktop, Cursor, Windsurf, and any other MCP client that supports the stdio transport. It authenticates to the Auris API using the OAuth2 client_credentials grant (M2M), so no user session is required. Token refresh is handled automatically.

Installation

Run with npx without a global install:

npx @auris/mcp

Or install globally:

npm install -g @auris/mcp

Node.js 20.9.0 or later is required.

Prerequisites

Before connecting an AI client to the MCP server you need an M2M application registered in Auris:

1. Open the Auris Console and navigate to Applications.
2. Create a new application of type M2M.
3. Copy the Client ID and Client Secret.
4. Ensure the application has the permissions needed for the tools you intend to use. Granting the admin:all permission gives the server access to every tool; you can scope it down to specific permissions if you want a narrower surface area.

Environment Variables

The server reads configuration exclusively from environment variables. No config file is used.

Required:

Optional:

Claude Desktop Configuration

Add the following block to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "auris-iam": {
      "command": "npx",
      "args": ["@auris/mcp"],
      "env": {
        "AURIS_DOMAIN": "https://auris.altovar.net",
        "AURIS_CLIENT_ID": "<your-m2m-client-id>",
        "AURIS_CLIENT_SECRET": "<your-m2m-client-secret>",
        "AURIS_TENANT": "<your-tenant-id>"
      }
    }
  }
}

Restart Claude Desktop after saving. The server will appear as auris-iam in the tool list.

Cursor Configuration

Add the MCP server under mcpServers in your Cursor settings (~/.cursor/mcp.json or the project-level .cursor/mcp.json):

{
  "mcpServers": {
    "auris-iam": {
      "command": "npx",
      "args": ["@auris/mcp"],
      "env": {
        "AURIS_DOMAIN": "https://auris.altovar.net",
        "AURIS_CLIENT_ID": "<your-m2m-client-id>",
        "AURIS_CLIENT_SECRET": "<your-m2m-client-secret>",
        "AURIS_TENANT": "<your-tenant-id>"
      }
    }
  }
}

Tool Groups

The server registers 49 tools organized into nine groups. Each group maps to a distinct area of the Auris API.

Users

Roles

Organizations

Applications

Sessions

Audit Logs

Webhooks

Fine-Grained Authorization

The FGA tools implement a Zanzibar-style relationship model compatible with the OpenFGA schema format. See the Fine-Grained Authorization guide for background.

Tenant

Access Control

By default, all 49 tools are registered and available to the AI agent. You can restrict which tools are visible using one of two mechanisms, evaluated in this order:

1. Deploy-time environment variable (AURIS_MCP_ALLOWED_TOOLS)

Set a comma-separated list of tool names or glob patterns:

# Only user and FGA tools
AURIS_MCP_ALLOWED_TOOLS="auris_list_users,auris_get_user,auris_fga_*"
 
# All tools in a group
AURIS_MCP_ALLOWED_TOOLS="auris_fga_*,auris_list_audit_logs"
 
# Every tool (no filtering — equivalent to leaving it unset)
AURIS_MCP_ALLOWED_TOOLS="auris_*"

2. Per-application DB allowlist

If AURIS_MCP_ALLOWED_TOOLS is not set, the server fetches the mcpAllowedTools field from the M2M application record (GET /api/applications/self) at startup. You can configure this list in the Auris Console under Applications → [your M2M app] → MCP Settings.

If neither is configured, all tools are registered.

Tools not in the allowlist are silently dropped before the MCP server starts — they will not appear in the client’s tool list at all.

Authentication Details

The server uses the OAuth2 client_credentials grant. At startup — and transparently before each API call when the token is within 60 seconds of expiry — it posts to POST /api/auth/token with grant_type=client_credentials. The resulting Bearer token and x-tenant header are attached to every downstream request.

No user interaction or browser redirect is involved. The M2M application must exist in the same tenant you set in AURIS_TENANT.

Required Permissions

The M2M application needs permissions that match the tools you expose. The simplest option is to grant admin:all and restrict surface area through the tool allowlist. For a minimal read-only setup, the following permissions are sufficient:

Related Pages

• M2M Authentication — How to create and configure M2M applications
• Fine-Grained Authorization — Background on the Zanzibar-style FGA model
• Audit Logs — Log format and available action types
• CLI Tool — Terminal-based management for scripting and CI/CD pipelines
• REST API Reference — Complete HTTP API for custom integrations