Configuration Reference

The server accepts configuration through environment variables and a settings.json file. Environment variables take precedence, so you can keep a base file and override specific values at runtime.

Environment variables

Variable	Required	Default	Description
`MAINWP_URL`	Yes		Base URL of your MainWP Dashboard
`MAINWP_USER`	Yes*		WordPress username that owns the Application Password
`MAINWP_APP_PASSWORD`	Yes*		WordPress Application Password
`MAINWP_TOKEN`	No		MainWP REST API bearer token. Not accepted by the Abilities API; see the note below
`MAINWP_SKIP_SSL_VERIFY`	No	`false`	Skip SSL certificate verification (development only)
`MAINWP_ALLOW_HTTP`	No	`false`	Allow HTTP URLs (credentials sent in plain text)
`MAINWP_SAFE_MODE`	No	`false`	Block all destructive operations
`MAINWP_REQUIRE_USER_CONFIRMATION`	No	`true`	Require two-step confirmation for destructive operations
`MAINWP_ALLOWED_TOOLS`	No		Comma-separated whitelist of tools
`MAINWP_BLOCKED_TOOLS`	No		Comma-separated blacklist of tools
`MAINWP_SCHEMA_VERBOSITY`	No	`standard`	Schema detail level: `standard` or `compact`
`MAINWP_RESPONSE_FORMAT`	No	`compact`	Tool response JSON: `compact` or `pretty`
`MAINWP_RATE_LIMIT`	No	`60`	Maximum API requests per minute (`0` disables)
`MAINWP_REQUEST_TIMEOUT`	No	`30000`	Request timeout in milliseconds
`MAINWP_MAX_RESPONSE_SIZE`	No	`10485760`	Maximum single response size in bytes (10MB)
`MAINWP_MAX_SESSION_DATA`	No	`52428800`	Maximum cumulative session data in bytes (50MB)
`MAINWP_RETRY_ENABLED`	No	`true`	Enable automatic retry for transient errors
`MAINWP_MAX_RETRIES`	No	`2`	Total attempts including the initial request
`MAINWP_RETRY_BASE_DELAY`	No	`1000`	Base delay between retries in milliseconds
`MAINWP_RETRY_MAX_DELAY`	No	`2000`	Maximum delay between retries in milliseconds
`MAINWP_ABILITY_NAMESPACES`	No	`mainwp`	Comma-separated namespace allowlist

* Required as a pair. This is the authentication method.

Authentication is MAINWP_USER + MAINWP_APP_PASSWORD. The Abilities API, which is the only API this server calls, authenticates through native WordPress and does not accept MainWP REST API bearer tokens. MAINWP_TOKEN is still read for compatibility and used when no Application Password credentials are present, but it will fail against the Abilities endpoints. Use an Application Password.

Configuration file

Create settings.json in one of these locations, checked in order:

./settings.json (the server’s working directory)
~/.config/mainwp-mcp/settings.json

As of @mainwp/mcp 1.2.0, a working-directory settings.json cannot loosen security settings: requireUserConfirmation: false, skipSslVerify: true, and allowHttp: true are ignored there, with a warning on stderr. Set those through environment variables or the per-user file.

{
  "dashboardUrl": "https://your-dashboard.com",
  "username": "admin",
  "appPassword": "xxxx xxxx xxxx xxxx xxxx xxxx",
  "skipSslVerify": false,
  "safeMode": false,
  "schemaVerbosity": "standard",
  "rateLimit": 60
}

Restrict permissions on any file holding credentials:

chmod 600 ~/.config/mainwp-mcp/settings.json

A JSON schema ships with the package as settings.schema.json for IDE autocompletion.

Field mapping

settings.json	Environment variable	Type
`dashboardUrl`	`MAINWP_URL`	string
`username`	`MAINWP_USER`	string
`appPassword`	`MAINWP_APP_PASSWORD`	string
`apiToken`	`MAINWP_TOKEN`	string
`skipSslVerify`	`MAINWP_SKIP_SSL_VERIFY`	boolean
`allowHttp`	`MAINWP_ALLOW_HTTP`	boolean
`safeMode`	`MAINWP_SAFE_MODE`	boolean
`requireUserConfirmation`	`MAINWP_REQUIRE_USER_CONFIRMATION`	boolean
`allowedTools`	`MAINWP_ALLOWED_TOOLS`	string[]
`blockedTools`	`MAINWP_BLOCKED_TOOLS`	string[]
`schemaVerbosity`	`MAINWP_SCHEMA_VERBOSITY`	string
`responseFormat`	`MAINWP_RESPONSE_FORMAT`	string
`rateLimit`	`MAINWP_RATE_LIMIT`	number
`requestTimeout`	`MAINWP_REQUEST_TIMEOUT`	number
`maxResponseSize`	`MAINWP_MAX_RESPONSE_SIZE`	number
`maxSessionData`	`MAINWP_MAX_SESSION_DATA`	number
`retryEnabled`	`MAINWP_RETRY_ENABLED`	boolean
`maxRetries`	`MAINWP_MAX_RETRIES`	number
`retryBaseDelay`	`MAINWP_RETRY_BASE_DELAY`	number
`retryMaxDelay`	`MAINWP_RETRY_MAX_DELAY`	number
`abilityNamespaces`	`MAINWP_ABILITY_NAMESPACES`	string[]

If both credential methods are present, the username plus Application Password pair takes precedence over apiToken.

Multiple Dashboards

Give each Dashboard its own folder containing its own settings.json, then point each MCP server entry at the right folder with cwd in your AI client’s configuration:

{
  "mcpServers": {
    "mainwp-staging": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "cwd": "/path/to/staging-credentials"
    }
  }
}

Because ./settings.json is checked first, each server instance picks up the credentials from its own working directory.

First-run setup

As of @mainwp/mcp 1.3.0, a server started without a Dashboard URL or credentials does not fail to launch. It connects to your AI client in setup mode: the MainWP tools stay hidden and two setup tools take their place, so you can finish configuration in the conversation instead of hunting through stderr.

mainwp_get_setup_status reports what is missing and returns setup instructions for your assistant to relay. If credentials are present but the Dashboard was unreachable at startup, calling it again retries the connection with the credentials already loaded.
mainwp_configure takes a Dashboard URL, username, and Application Password, verifies them against the Dashboard, and saves them.

There are two ways to finish setup. Adding the credentials yourself is the recommended path. Put MAINWP_URL, MAINWP_USER, and MAINWP_APP_PASSWORD in the env block of this server’s entry in your MCP client config, or in ~/.config/mainwp-mcp/settings.json, then restart the client. The password never passes through the conversation. Pasting them in chat is also fine. Your assistant collects the three values and calls mainwp_configure. The server verifies them, writes them to ~/.config/mainwp-mcp/settings.json with owner-only permissions (0600, in a 0700 directory), and scrubs the password from its own logs and from every response. An Application Password is separate from your WordPress login password and you can revoke it from your profile at any time.

Worth knowing before you choose: a password pasted in chat also becomes part of your chat history, which your AI client and provider may retain. If that bothers you later, revoke the password and create a new one.

Once configuration succeeds, the full tool list appears in the same session for clients that honor MCP list-changed notifications. Clients that do not refresh on their own need a reconnect or restart. mainwp_configure refuses rather than saving something that would be ignored or overridden:

Any connection environment variable (MAINWP_URL, MAINWP_USER, MAINWP_APP_PASSWORD, MAINWP_TOKEN) is set. Environment variables outrank the file it writes, so finish setup there.
A settings.json exists in the server’s working directory. That file is loaded first and would permanently shadow the saved credentials.
The server already has credentials loaded, whether or not they are currently working. See the next section.

It writes only those three connection fields, never security settings, and blocking mainwp_configure through blockedTools removes chat-based setup entirely while leaving the manual path available.

Why setup will not replace credentials you already have

Chat-based setup can get you connected the first time, but it can never overwrite a connection you set up yourself. That line is deliberate, and it is worth knowing where it costs you something. The reason is that an assistant acts on text, and text can come from places you did not intend. A page it read, a site name, or an ability description returned by a server could carry instructions aimed at the assistant rather than at you. If setup could overwrite a working configuration, that kind of injected instruction could quietly repoint your server at someone else’s Dashboard, and every command you ran afterwards would go there. Restricting setup to the case where there is nothing to overwrite removes that possibility, because a server that has no credentials has nothing worth stealing. A tempting middle ground is to allow it when the stored credentials are provably wrong, since the Dashboard rejected them with an authentication error. We do not do that, because it would let the remote side decide when your local configuration may be replaced: a Dashboard that had been compromised, or a connection someone was tampering with, could reject a valid login on purpose to unlock the replacement path, without ever knowing your password. The cost is real, and it lands in one place. If you rotate the Application Password in WordPress, or the stored one is wrong for any other reason, retrying will not help, because the retry reuses the same credentials the Dashboard is already refusing. You have to put the new password in ~/.config/mainwp-mcp/settings.json or your client’s env block yourself and restart the client. That is the same edit you would have made to set the server up manually in the first place, and it takes a minute.

Behavior settings

safeMode blocks every destructive operation at the server. Explained on Safety & Permissions.
requireUserConfirmation controls the two-step preview/confirm flow for destructive operations (default on). Also on Safety & Permissions.
allowedTools / blockedTools filter the tool catalog. See Restrict Available Tools.
schemaVerbosity trades tool-description detail for context tokens. See Optimize Token Usage.
abilityNamespaces controls which plugins’ abilities are exposed. See Use Abilities from Other Plugins.
responseFormat switches tool response JSON between compact (default) and pretty.

Resource limits

These guard against runaway operations and oversized responses.

Setting	Default	Behavior when exceeded
`rateLimit`	60/min	Calls fail until the window passes; `0` disables
`requestTimeout`	30000 ms	The request is aborted
`maxResponseSize`	10 MB	The single response is rejected
`maxSessionData`	50 MB	Subsequent calls fail with `RESOURCE_EXHAUSTED` until the server restarts

Retry logic

Transient errors (HTTP 5xx, HTTP 429, network resets) are retried with exponential backoff and jitter. Only read-only operations are retried, which preserves idempotency; writes fail immediately. Permanent errors (4xx other than 429, authentication failures) are never retried. Total time across retries never exceeds requestTimeout, and retries bypass the rate limiter to avoid deadlocks. Disable for automation or testing with retryEnabled: false.

SSL

The server verifies certificates and refuses plain HTTP by default. skipSslVerify and allowHttp exist for local development against self-signed or HTTP-only environments.

skipSslVerify disables certificate verification entirely and allowHttp sends credentials unencrypted. Use them only in isolated development environments, never in production or on untrusted networks.

Getting Started

Understanding MainWP

Dashboard

Sites

Users

Updates

Plugins

Themes

Content Operations

Clients

MCP Server

API Reference

Troubleshooting

Customization

Advanced

Resources

Environment variables

Configuration file

Field mapping

Multiple Dashboards

First-run setup

Why setup will not replace credentials you already have

Behavior settings

Resource limits

Retry logic

SSL

​Environment variables

​Configuration file

​Field mapping

​Multiple Dashboards

​First-run setup

​Why setup will not replace credentials you already have

​Behavior settings

​Resource limits

​Retry logic

​SSL

Environment variables

Configuration file

Field mapping

Multiple Dashboards

First-run setup

Why setup will not replace credentials you already have

Behavior settings

Resource limits

Retry logic

SSL