@kotauth/mcp

MCP (Model Context Protocol) server for KotAuth — manage users, roles, groups, applications, sessions, audit logs, user attributes, claim mappers, API keys, resource servers, webhooks, workspace config, passkeys, and Email OTP from AI assistants like Claude, Cursor, and any MCP-compatible client. 56 tools across 14 domains.

Quick Start

npx @kotauth/mcp

Configuration

The server requires three environment variables:

| Variable | Description | Example | |---|---|---| | KOTAUTH_BASE_URL | Your KotAuth instance URL | https://auth.example.com | | KOTAUTH_TENANT_SLUG | Workspace slug to operate on | my-workspace | | KOTAUTH_API_KEY | API key with required scopes | kauth_my-workspace_abc... |

Create an API key in the KotAuth Admin Console under Settings → API Keys. Grant the scopes you need (e.g. users:read, users:write, roles:read).

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kotauth": {
      "command": "npx",
      "args": ["-y", "@kotauth/mcp"],
      "env": {
        "KOTAUTH_BASE_URL": "https://auth.example.com",
        "KOTAUTH_TENANT_SLUG": "my-workspace",
        "KOTAUTH_API_KEY": "kauth_my-workspace_..."
      }
    }
  }
}

Claude Code

claude mcp add kotauth -- npx -y @kotauth/mcp \
  --env KOTAUTH_BASE_URL=https://auth.example.com \
  --env KOTAUTH_TENANT_SLUG=my-workspace \
  --env KOTAUTH_API_KEY=kauth_my-workspace_...

Available Tools

Users (10 tools)

• list_users — List users, optionally filter by username/email/name
• get_user — Get a specific user by ID
• create_user — Create a new user with username, email, and password
• update_user — Update a user's email or display name
• disable_user — Disable a user account (soft delete)
• assign_user_role — Assign a role to a user
• remove_user_role — Remove a role from a user
• invite_user — Invite a user via email with a branded activation link
• send_password_reset — Send a password reset email to a user
• set_temporary_password — Set a temporary password with mandatory change on next login

Roles (5 tools)

• list_roles — List all roles (tenant and client scoped)
• get_role — Get a specific role by ID with assigned users
• create_role — Create a new role
• update_role — Update a role's description
• delete_role — Delete a role

Groups (6 tools)

• list_groups — List all groups with hierarchy
• get_group — Get a specific group with members and parent
• create_group — Create a group (optionally nested under a parent)
• update_group — Update a group's name or description
• delete_group — Delete a group
• manage_group_member — Add or remove a user from a group

Applications (8 tools)

• list_applications — List OAuth2/OIDC clients
• get_application — Get a specific application by ID
• update_application — Update an application's settings
• create_application — Create a new OAuth2 application (returns client secret once for confidential apps)
• regenerate_client_secret — Regenerate the client secret for a confidential application
• delete_application — Soft-delete an application
• list_default_roles — List roles auto-assigned at self-registration
• set_default_roles — Replace the set of default roles for an application

Sessions (2 tools)

• list_sessions — List active sessions
• revoke_session — Force-terminate a session

Audit (1 tool)

• query_audit_logs — Query immutable audit events with filters

User Attributes (3 tools)

• list_user_attributes — List all custom attributes for a user
• set_user_attribute — Set a key-value attribute on a user (creates or updates)
• delete_user_attribute — Remove an attribute from a user

Claim Mappers (3 tools)

• list_claim_mappers — List all claim mappers for the workspace
• set_claim_mapper — Map a user attribute to a JWT claim name
• delete_claim_mapper — Remove a claim mapper

API Keys (3 tools)

• list_api_keys — List all API keys (without secret values)
• create_api_key — Create a new API key with scopes (raw key returned once)
• delete_api_key — Revoke an API key

Resource Servers (7 tools)

• list_resource_servers — List all resource servers (APIs)
• get_resource_server — Get a specific resource server by ID
• create_resource_server — Register a new resource server with identifier and scopes
• update_resource_server — Update a resource server's name, description, or scopes
• delete_resource_server — Delete a resource server
• list_app_resource_servers — List resource servers authorized for an application
• set_app_resource_servers — Set which resource servers an application can access

Webhooks (3 tools)

• list_webhooks — List all webhook endpoint subscriptions
• create_webhook — Create a webhook endpoint (HMAC secret returned once)
• delete_webhook — Delete a webhook endpoint

Workspace (1 tool)

• get_workspace — Get workspace configuration (sign-in methods, policies, settings)

Passkeys (2 tools)

• list_user_passkeys — List a user's FIDO2/WebAuthn passkey credentials
• delete_passkey — Delete a specific passkey credential

Auth (2 tools)

• send_otp — Send a 6-digit Email OTP code for passwordless authentication
• verify_otp — Verify an OTP code and receive an authorization code

Required API Key Scopes

Each tool requires specific scopes on the API key:

| Tools | Scope | |---|---| | list_users, get_user | users:read | | create_user, update_user, disable_user, assign/remove role, invite_user, send_password_reset, set_temporary_password, delete_passkey | users:write | | list_user_passkeys | users:read | | list_roles, get_role | roles:read | | create_role, update_role, delete_role | roles:write | | list_groups, get_group | groups:read | | create_group, update_group, delete_group, manage_group_member | groups:write | | list_applications, get_application, list_default_roles | applications:read | | create_application, update_application, delete_application, regenerate_client_secret, set_default_roles | applications:write | | list_sessions | sessions:read | | revoke_session | sessions:write | | query_audit_logs | audit_logs:read | | list_user_attributes | user_attributes:read | | set_user_attribute, delete_user_attribute | user_attributes:write | | list_claim_mappers | claim_mappers:read | | set_claim_mapper, delete_claim_mapper | claim_mappers:write | | list_api_keys | api_keys:read | | create_api_key, delete_api_key | api_keys:write | | list_resource_servers, get_resource_server, list_app_resource_servers | resource_servers:read | | create_resource_server, update_resource_server, delete_resource_server, set_app_resource_servers | resource_servers:write | | list_webhooks | webhooks:read | | create_webhook, delete_webhook | webhooks:write | | get_workspace | workspace:read | | send_otp | auth:send-otp | | verify_otp | auth:verify-otp |

Development

git clone https://github.com/kotauth/kotauth-mcp.git
cd kotauth-mcp
npm install
npm run build

Test locally with the MCP inspector:

KOTAUTH_BASE_URL=http://localhost:8080 \
KOTAUTH_TENANT_SLUG=master \
KOTAUTH_API_KEY=kauth_master_... \
npx @modelcontextprotocol/inspector node dist/index.js

License

MIT — see LICENSE.