AuthJoy MCP Server

Model Context Protocol server for AuthJoy authentication

Expose AuthJoy's powerful authentication API as tools for AI coding agents like Claude, enabling them to perform authentication operations programmatically.

🎯 What is This?

The AuthJoy MCP Server implements the Model Context Protocol to expose AuthJoy's authentication capabilities as tools that AI agents can use. This allows Claude (and other MCP-compatible AI assistants) to:

• Register new users
• Authenticate users
• Manage passwords
• Enable/disable MFA
• Handle sessions
• Send magic links
• Generate social OAuth URLs
• ...and more!

🚀 Quick Start

1. Installation

cd packages/mcp-server
pnpm install

2. Configuration

Create a .env file:

cp .env.example .env

Edit .env with your AuthJoy credentials:

AUTHJOY_API_URL=http://localhost:3000
AUTHJOY_TENANT_ID=your-tenant-id
AUTHJOY_API_KEY=aj_live_xxxxxxxxxx

3. Build

pnpm build

4. Test Locally

pnpm dev

🔌 Integration with Claude Desktop

Install in Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "authjoy": {
      "command": "node",
      "args": ["/absolute/path/to/authjoy/packages/mcp-server/dist/index.js"],
      "env": {
        "AUTHJOY_API_URL": "http://localhost:3000",
        "AUTHJOY_TENANT_ID": "your-tenant-id",
        "AUTHJOY_API_KEY": "your-api-key"
      }
    }
  }
}

Or use the dev version (no build required):

{
  "mcpServers": {
    "authjoy": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/authjoy/packages/mcp-server/src/index.ts"],
      "env": {
        "AUTHJOY_API_URL": "http://localhost:3000",
        "AUTHJOY_TENANT_ID": "your-tenant-id",
        "AUTHJOY_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop

After updating the config, restart Claude Desktop for changes to take effect.

🛠️ Available Tools

The MCP server exposes these authentication tools:

User Management

user_signup

Register a new user account.

Parameters:

• email (string, required) - User email address
• password (string, required) - Password (min 8 chars)
• displayName (string, optional) - Display name
• sendEmailVerification (boolean, optional) - Send verification email

Example:

Use the user_signup tool to create a new account for [email protected]

user_signin

Authenticate a user with email/password.

Parameters:

• email (string, required) - User email
• password (string, required) - User password

Example:

Sign in the user [email protected] with password "secret123"

user_get

Get user profile information.

Parameters:

• userId (string, required) - User ID or UID

user_update

Update user profile.

Parameters:

• userId (string, required) - User ID
• displayName (string, optional) - New display name
• photoURL (string, optional) - New photo URL

user_delete

Delete a user account.

Parameters:

• userId (string, required) - User ID

Password Management

password_reset_request

Request a password reset email.

Parameters:

• email (string, required) - User email address

Example:

Send a password reset email to [email protected]

password_reset_confirm

Complete password reset with token.

Parameters:

• token (string, required) - Reset token from email
• newPassword (string, required) - New password (min 8 chars)

password_update

Update password for authenticated user.

Parameters:

• userId (string, required) - User ID
• currentPassword (string, required) - Current password
• newPassword (string, required) - New password (min 8 chars)

Multi-Factor Authentication (MFA)

mfa_enroll

Enroll user in MFA (returns QR code for TOTP).

Parameters:

• userId (string, required) - User ID
• method (string, optional) - Method: 'totp', 'sms', or 'email' (default: 'totp')

Example:

Enroll user-123 in TOTP multi-factor authentication

mfa_verify

Verify MFA code.

Parameters:

• userId (string, required) - User ID
• code (string, required) - 6-digit MFA code
• enrollmentId (string, optional) - Enrollment ID if verifying enrollment

Example:

Verify MFA code 123456 for user-123

mfa_unenroll

Disable MFA for a user.

Parameters:

• userId (string, required) - User ID

Session Management

session_list

List all active sessions for a user.

Parameters:

• userId (string, required) - User ID

Example:

Show me all active sessions for user-123

session_revoke

Revoke a specific session.

Parameters:

• sessionId (string, required) - Session ID to revoke

session_revoke_all

Sign out user from all devices.

Parameters:

• userId (string, required) - User ID

Example:

Sign out user-123 from all devices

Passwordless Authentication

magic_link_send

Send a magic link (passwordless login) email.

Parameters:

• email (string, required) - User email address
• redirectUrl (string, optional) - Redirect URL after auth

Example:

Send a magic link to [email protected]

social_auth_url

Get OAuth URL for social authentication.

Parameters:

• provider (string, required) - Provider: 'google', 'github', 'facebook', 'twitter', 'microsoft'
• redirectUrl (string, optional) - Redirect URL after auth

Example:

Get Google OAuth sign-in URL

💬 Example Conversations with Claude

Once configured, you can interact with AuthJoy through Claude:

Example 1: User Registration

You: Create a new user account with email [email protected] and password SecurePass123

Claude: I'll create a new user account using the AuthJoy MCP server.
[Uses user_signup tool]
✓ Successfully created user account for [email protected]
User ID: user-abc123
Email verified: false

Example 2: Enable MFA

You: Enable TOTP multi-factor authentication for user user-abc123

Claude: I'll enroll this user in TOTP-based MFA.
[Uses mfa_enroll tool]
✓ MFA enrollment successful!
QR Code: [displays QR code URL]
Secret: JBSWY3DPEHPK3PXP
Backup codes: [list of 10 codes]

Scan the QR code with Google Authenticator or Authy to complete setup.

Example 3: Session Management

You: Show me all active sessions for user user-abc123 and sign them out from all devices

Claude: I'll first list the active sessions, then revoke them all.
[Uses session_list tool]
Found 3 active sessions:
- Session 1: Chrome on macOS (last active 5 mins ago)
- Session 2: Firefox on Windows (last active 2 hours ago)
- Session 3: Mobile Safari on iOS (last active 1 day ago)

[Uses session_revoke_all tool]
✓ All sessions revoked. User has been signed out from all devices.

Example 4: Password Reset Flow

You: User forgot their password. Email is [email protected]

Claude: I'll send a password reset email.
[Uses password_reset_request tool]
✓ Password reset email sent to [email protected]
Check your inbox for the reset link (valid for 1 hour).

🧪 Testing with MCP Inspector

Use the official MCP Inspector to test your server:

npx @modelcontextprotocol/inspector node dist/index.js

This opens a web interface where you can:

• View all available tools
• Test tool calls interactively
• See request/response payloads
• Debug errors

🔧 Development

Project Structure

packages/mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript
├── package.json          # Dependencies & scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Example environment variables
└── README.md             # This file

Build

pnpm build

Development Mode (with auto-reload)

pnpm dev

Type Checking

pnpm type-check

📚 Resources

• MCP Specification: https://modelcontextprotocol.io/
• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
• MCP Inspector: https://modelcontextprotocol.io/docs/tools/inspector
• AuthJoy API Docs: ../api/docs/API_REFERENCE.md

🔐 Security Considerations

API Key Protection

• Never commit .env file to version control
• Use environment variables in production
• Rotate API keys regularly

Permissions

• MCP server has full access to AuthJoy API
• Only give Claude access to MCP server in trusted environments
• Consider creating a separate tenant for testing

Rate Limiting

• AuthJoy API has rate limits per endpoint
• MCP server respects these limits
• High-frequency operations may be throttled

🐛 Troubleshooting

"AUTHJOY_TENANT_ID and AUTHJOY_API_KEY must be set"

Solution: Create .env file with valid credentials

"Connection refused" or "Network error"

Solution: Ensure AuthJoy API is running at the configured URL

Claude doesn't see the tools

Solution:

1. Restart Claude Desktop after config changes
2. Check absolute paths in config are correct
3. View Claude logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Tool calls fail with 401 Unauthorized

Solution: Verify API key is correct and has proper permissions

📝 License

MIT

🤝 Contributing

Contributions welcome! Please check the main AuthJoy repository for contribution guidelines.

Built with ❤️ using the Model Context Protocol