Skip to content
Kotauth

Overview

The @kotauth/mcp package is an MCP server that connects AI assistants — Claude, Cursor, Windsurf, and any other MCP-compatible client — directly to your Kotauth instance. It exposes 25 tools across 8 domains, letting you manage users, roles, groups, applications, sessions, audit logs, user attributes, and claim mappers through natural language.

Instead of writing HTTP requests or navigating the admin console, you describe what you want and the AI assistant calls the right Kotauth API endpoints automatically.

What is MCP?

Section titled “What is MCP?”

The Model Context Protocol is an open standard that lets AI assistants interact with external systems through typed tools. An MCP server declares a set of tools with parameter schemas — the AI assistant reads those schemas and decides which tools to call based on your request.

Kotauth’s MCP server wraps the REST API v1 so that every operation available through the API is also available through natural language.

What you can do

Section titled “What you can do”

With @kotauth/mcp connected, you can ask your AI assistant to:

  • Create and manage users — provision accounts, update profiles, disable users, assign roles
  • Configure RBAC — create roles with tenant or client scope, build group hierarchies, manage membership
  • Manage OAuth applications — list registered clients, update redirect URIs, change access types
  • Monitor sessions — list active sessions with IP addresses and expiry times, revoke individual sessions
  • Query audit logs — filter by event type, user, and time range to investigate activity
  • Manage user attributes — set, list, and delete per-user key-value metadata
  • Configure claim mappers — project user attributes into JWT access and ID tokens

All operations respect the same scope-based access control as the REST API. An API key with users:read scope can list users but not create them.

Architecture

Section titled “Architecture”
graph LR
    A[AI Assistant<br/>Claude / Cursor] -->|stdio| B["@kotauth/mcp<br/>(Node.js)"]
    B -->|HTTP / Bearer token| C["Kotauth REST API<br/>/t/{slug}/api/v1"]
    C --> D[(PostgreSQL)]

The MCP server runs as a local process on your machine. It communicates with the AI assistant over stdio (standard input/output) and with your Kotauth instance over HTTP using a scoped API key. No data flows through third-party servers — the MCP server talks directly to your Kotauth deployment.

Requirements

Section titled “Requirements”
  • Node.js 18+ (for running the MCP server)
  • A running Kotauth instance (local or remote)
  • An API key with the scopes you need (created in the admin console under Settings → API Keys)

Next steps

Section titled “Next steps”