Skip to main content
These endpoints manage the local username/password users stored in mcp_settings.json (or the mcphub_user table when the database backend is enabled). All endpoints require an authenticated admin (isAdmin: true). For OAuth/social accounts created via Better Auth, see /api/better-auth/* instead — those records live in a separate table and are not managed through this API.

GET /api/users

List all users.

GET /api/users/:username

Get a single user.

POST /api/users

Create a user.

PUT /api/users/:username

Update a user.

DELETE /api/users/:username

Delete a user.

GET /api/users-stats

Aggregate user counts.

​
Get All Users

  • Endpoint: GET /api/users
  • Authentication: Required (admin only)
  • Response: The password field is stripped from every record.
{
  "success": true,
  "data": [
    { "username": "admin", "isAdmin": true },
    { "username": "alice", "isAdmin": false }
  ]
}

​
Get a User

  • Endpoint: GET /api/users/:username
  • Authentication: Required (admin only)
  • Response:
{
  "success": true,
  "data": { "username": "alice", "isAdmin": false }
}
Returns 404 if the user does not exist.

​
Create a User

  • Endpoint: POST /api/users
  • Authentication: Required (admin only)
  • Body:
{
  "username": "alice",
  "password": "P@ssw0rd-123",
  "isAdmin": false
}
FieldTypeRequiredDescription
usernamestringyesMust be unique.
passwordstringyesMust satisfy the configured password policy (see src/utils/passwordValidation.ts).
isAdminbooleannoDefaults to false.
  • Returns 400 if username/password are missing, the password is too weak, or the username is already taken.
  • Returns 201 with the new user (password stripped) on success.
The user model does not have per-user servers or groups lists. Server visibility is governed by the owner field on each server and by the group membership recorded on the group itself. See Group Management and MCP Settings.

​
Update a User

  • Endpoint: PUT /api/users/:username
  • Authentication: Required (admin only)
  • Body (at least one field is required):
{
  "isAdmin": true,
  "newPassword": "Newp@ssw0rd"
}
FieldTypeDescription
isAdminbooleanPromote/demote the user.
newPasswordstringReplace the user’s password. Must satisfy the password policy.
  • Returns 400 if neither field is supplied, the password fails validation, or the request would demote the last remaining admin.
  • Returns 404 if the username does not exist.
Username is the primary key — to rename a user, delete and recreate them. Other profile fields (email, display name, etc.) are not currently supported on the local user model.

​
Delete a User

  • Endpoint: DELETE /api/users/:username
  • Authentication: Required (admin only)
  • Restrictions:
    • You cannot delete your own account.
    • You cannot delete the last admin.
{
  "success": true,
  "message": "User deleted successfully"
}

​
Get User Statistics

  • Endpoint: GET /api/users-stats
  • Authentication: Required (admin only)
{
  "success": true,
  "data": {
    "totalUsers": 5,
    "adminUsers": 1,
    "regularUsers": 4
  }
}
The stats endpoint reports only aggregate counts; per-server or per-group breakdowns are not produced here.