---
title: "corestack_external_db_user_add"
url: https://docs.corefinity.com/mcp/tools/corestack_external_db_user_add
type: tool
last_updated: 2026-11-13
feature: database
related:
  - https://docs.corefinity.com/api/reference/database/create-site-database-user.md
  - https://docs.corefinity.com/guides/sites/database/database-users.md
---
# corestack_external_db_user_add

**Add a database user.** Add a database user to an environment: internal (connects from inside the site: its crons, the terminal and the SSH tunnel) or external (connects through external access, from the allowed addresses only), read-only or read-write on the environment's own database. A generated password is shown once, in the person's browser. Scope: write. Also needs exec when reveal_to_agent is true. Long-running: answers with a task. The secret opens in the person's browser; set reveal_to_agent to true to receive it yourself (needs exec).

- Scope: `write`
- Also needs `exec` when a generated password
- Confirmation: `confirm_read_write`
- Runs as a task: yes
- Returns a secret only when `reveal_to_agent` is set

## When to use it

Add a database user to an environment, for a reporting tool, an agency's script or an outside system such as an order system or ERP:

- `internal`: connects from inside the site only, through its crons, the terminal or the SSH tunnel.
- `external`: connects through external database access, from the allowed addresses only. Turn external access on first with `corestack_external_db_enable`.

Read-only is SELECT and SHOW VIEW on the environment's own database. Read-write adds INSERT, UPDATE, DELETE, CREATE TEMPORARY TABLES, LOCK TABLES and EXECUTE, never users, grants or another database; it can change and delete data, which only a snapshot restore takes back, so ask the person first and send `confirm_read_write: "read-write"`.

The password is either one you send (`{"mode": "set", "value": ...}`) or one the Control Panel makes (`{"mode": "generate"}`, 24 characters). A generated password is shown once, in the person's browser; with exec and `reveal_to_agent: true` it is given to you when the task completes. The Control Panel keeps only its hash, so it cannot be shown again later: rotate it with `corestack_external_db_user_password_rotate` if it is lost.

The call answers a task on the change; it usually applies within a minute.

## Inputs

- `site_id` (integer, ≥ 1, required)
- `kind` (string, required): `internal` or `external`. External needs external access on.
- `username` (string, 3–32 characters, required): lower-case letters, digits and underscores, starting with a letter; not used by another user of this environment.
- `scope` (string, required): `read_only` or `read_write`.
- `password` (object, required): `{"mode": "generate"}`, or `{"mode": "set", "value": "..."}` with 12 to 64 printable ASCII characters and no quotes, backticks or backslashes.
- `max_user_connections` (integer or null, ≥ 0): external users only, the most connections at once; null or absent for none.
- `max_statement_time` (integer or null, ≥ 0): external users only, the longest query in seconds; null or absent for none.
- `require_tls` (boolean): external users only, refuse connections without TLS (encrypted, not CA-verified).
- `confirm_read_write` (string): with `scope: read_write`, the text `read-write`, typed after the person agreed.
- `reveal_to_agent` (boolean, default `false`): Return the secret to you instead of opening it in the person's browser. Needs exec.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "confirm_read_write": {
      "description": "With scope read_write: type read-write (the user can change and delete data).",
      "type": "string"
    },
    "kind": {
      "description": "external needs external access on (corestack_external_db_enable).",
      "enum": [
        "internal",
        "external"
      ],
      "type": "string"
    },
    "max_statement_time": {
      "description": "External users: the longest query in seconds; null for none.",
      "type": [
        "integer",
        "null"
      ]
    },
    "max_user_connections": {
      "description": "External users: most connections at once; null for none.",
      "type": [
        "integer",
        "null"
      ]
    },
    "password": {
      "additionalProperties": false,
      "properties": {
        "mode": {
          "description": "generate: 24 characters made for you and shown once in the person's browser; set: your own `value`.",
          "enum": [
            "generate",
            "set"
          ],
          "type": "string"
        },
        "value": {
          "description": "With mode set: 12 to 64 printable ASCII characters, no quotes, backticks or backslashes.",
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "type": "object"
    },
    "require_tls": {
      "description": "External users: refuse connections without TLS (encrypted, not CA-verified).",
      "type": "boolean"
    },
    "reveal_to_agent": {
      "default": false,
      "description": "Return the secret to you instead of opening it in the person's browser. Needs exec.",
      "type": "boolean"
    },
    "scope": {
      "enum": [
        "read_only",
        "read_write"
      ],
      "type": "string"
    },
    "site_id": {
      "minimum": 1,
      "type": "integer"
    },
    "username": {
      "description": "Lower-case letters, digits and underscores, starting with a letter.",
      "type": "string"
    }
  },
  "required": [
    "site_id",
    "kind",
    "username",
    "scope",
    "password"
  ],
  "type": "object"
}
```

## Refusals

- `confirm_mismatch`: a read-write user without `confirm_read_write: "read-write"`; nothing changed.
- `external_off`: an external user while external access is not on.
- `user_cap`: the environment has 10 users already, or 5 external ones.
- `invalid_arguments`: the name is taken, malformed or reserved ("That name is reserved. Choose another." is the one answer for every reserved name), the password breaks its rules, or limits or TLS were sent for an internal user; `fields` names each.
- `busy`: another change to this environment is applying; try again when it finishes.
- `deleted`: the site is deleted (in its grace period); restore it with corestack_site_restore_deleted first.
- `provisioning`: the site is still being created.
- `managed_elsewhere` (message: "This site is managed by another control panel"): another control panel manages this site, so use that control panel for it. This is refused before anything else about the site, as in the Control Panel and the API. Nothing was done.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_external_db_user_add",
  "arguments": {
    "site_id": 4211,
    "kind": "internal",
    "username": "reporting_ro",
    "scope": "read_only",
    "password": {
      "mode": "generate"
    }
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_external_db_user_add with site_id 4211, kind internal, username reporting_ro, scope read_only, password {"mode":"generate"}. (Add a database user.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/corestack/sites/{site}/database/users](https://docs.corefinity.com/api/reference/database/create-site-database-user.md)
- Guide: [Database users](https://docs.corefinity.com/guides/sites/database/database-users.md)
