Setup & Configuration

Prerequisites

Before connecting the MCP server, you need three things from your Kotauth instance:

1. Base URL — the root URL of your Kotauth deployment (e.g. https://auth.yourdomain.com)
2. Workspace slug — the slug of the workspace you want to manage (e.g. my-app)
3. API key — a key with the scopes required for the tools you want to use

Creating an API key

1. Open the admin console at {baseUrl}/admin
2. Navigate to the workspace you want to manage
3. Go to Settings → API Keys
4. Click Create API Key and select the scopes you need
5. Copy the key — it is shown exactly once

Store your API key in a secrets manager or environment variable. If you lose it, delete it and create a new one.

See the scopes reference below for which scopes each tool requires.

Installation

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop. You should see a hammer icon indicating the MCP tools are available.

Add the server from your terminal:

claude mcp add kotauth \
  -e KOTAUTH_BASE_URL=https://auth.yourdomain.com \
  -e KOTAUTH_TENANT_SLUG=my-app \
  -e KOTAUTH_API_KEY=kauth_my-app_sk_xxxxxxxx \
  -- npx -y @kotauth/mcp

The server is immediately available in your Claude Code session.

Run the MCP server directly with environment variables:

KOTAUTH_BASE_URL=https://auth.yourdomain.com \
KOTAUTH_TENANT_SLUG=my-app \
KOTAUTH_API_KEY=kauth_my-app_sk_xxxxxxxx \
npx @kotauth/mcp

This is useful for testing with the MCP Inspector:

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

Environment variables

Variable	Required	Description
KOTAUTH_BASE_URL	Yes	Root URL of your Kotauth instance
KOTAUTH_TENANT_SLUG	Yes	Workspace slug to operate on
KOTAUTH_API_KEY	Yes	API key with required scopes

Each MCP server instance is bound to a single workspace. To manage multiple workspaces, configure multiple MCP server entries with different slugs and API keys.

Scope reference

The MCP server enforces the same scope model as the REST API. Each tool requires specific scopes on the API key:

Tools	Required scope
list_users, get_user	users:read
create_user, update_user, disable_user, assign_user_role, remove_user_role	users:write
list_roles	roles:read
create_role, delete_role	roles:write
list_groups	groups:read
create_group, delete_group, manage_group_member	groups:write
list_applications	applications:read
update_application	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

For a read-only reporting key, select only the `:read` scopes. For a full administration key, select all scopes. Always follow the principle of least privilege.

Verifying the connection

After setup, ask your AI assistant:

List all users in this workspace.

If the connection is working, the assistant will call the list_users tool and return user data from your Kotauth instance. If you see an error, check that your base URL is reachable, the workspace slug is correct, and the API key has users:read scope.

Updating

The MCP server is installed via npx, which always fetches the latest published version. To pin a specific version:

"args": ["-y", "@kotauth/mcp@0.1.0"]

Next steps

• Tool Reference — parameters, return types, and required scopes for all 25 tools
• Examples & Recipes — common workflows