Configuring Easy MCP AI with wp-config.php Constants

Every deployment-level setting in Easy MCP AI can be defined as a constant in wp-config.php or as an environment variable, instead of being saved from the admin screens. A setting defined this way is part of the site configuration: it applies from the moment WordPress loads, the matching field in the admin becomes read-only, and a site administrator cannot change it. This is built for hosting companies, agencies and anyone who provisions sites from a template or a pipeline and needs rate limits, tool restrictions, OAuth policy or history capture to be the same on every site.

In this article

• When to use constants
• How a setting is resolved
• Where to define them
  • In wp-config.php
  • As environment variables
  • On multisite
• Value formats
• What changes in the admin
• Export the current settings
• Settings reference
  • General
  • OAuth
  • Change History
  • Long-running tasks
  • Proxies and site presentation
• Credential hashing key
• What cannot be set by constant

When to use constants

Use a constant when a value should be decided once, by whoever manages the hosting, rather than per site by an administrator:

• The same policy must hold across many sites, and it must not drift.
• The value belongs in version control or in a secrets manager next to the rest of the site image.
• Nobody with access to the WordPress admin should be able to widen it, even by accident.

For a single site that one person manages, the admin screens under Easy MCP AI remain the simpler choice. Constants and admin settings can be mixed freely: only the settings you define are locked, everything else stays editable.

Related guides

Trusted Proxies covers the two constants that let the plugin see the visitor address behind a proxy or CDN. White-Label and Hidden Admin covers the constants that rename the plugin and hide its admin screens.

How a setting is resolved

Each setting is looked up in this order, and the first source that defines it wins:

1. A constant named EASY_MCP_AI_ followed by the setting name in upper case, for example EASY_MCP_AI_RATE_LIMIT_PER_MINUTE.
2. An environment variable of the same name.
3. The value saved from the admin screens.
4. The setting's built-in default.

A constant set to false or an environment variable set to an empty string still counts as defined. It overrides the saved value rather than falling through to it, so you can explicitly switch a feature off or clear a list from configuration.

Every value is validated before it is used. An invalid value, such as a rate limit of abc or a capability the plugin does not accept, does not fall through to the saved value. The setting's default applies instead, and an administrator notice names the constant so the mistake is easy to find. The notice never prints the value itself. Two restrictions are handled more strictly, so a typo can never open access: an invalid IP Whitelist refuses every request until it is corrected, and an invalid disabled-tools or whitelist-tools list makes every tool unavailable.

Developer filters such as easy_mcp_ai_oauth_enabled run after this resolution and can still change the final value.

Where to define them

In wp-config.php

Add the define() lines to wp-config.php above the line that reads /* That's all, stop editing! Happy publishing. */:

define( 'EASY_MCP_AI_RATE_LIMIT_PER_MINUTE', 30 );
define( 'EASY_MCP_AI_FORCE_DRAFT_ON_CREATE', true );
define( 'EASY_MCP_AI_OAUTH_MIN_CAPABILITY', 'manage_options' );
define( 'EASY_MCP_AI_DISABLED_TOOLS', array( 'wp_delete_post', 'wp_delete_page' ) );
define( 'EASY_MCP_AI_OAUTH_DCR_ENABLED', false );

PHP may cache wp-config.php through OPcache. After changing a constant, allow OPcache's normal revalidation interval to pass, or restart the PHP workers, before checking the result.

As environment variables

The same names work as environment variables, which suits container images and secrets managers:

EASY_MCP_AI_RATE_LIMIT_PER_MINUTE=30
EASY_MCP_AI_DISABLED_TOOLS=wp_delete_post,wp_delete_page

The variable has to reach the PHP process that serves WordPress. PHP-FPM clears the environment by default, so set clear_env = no in the pool configuration or add an env[EASY_MCP_AI_…] line for each variable. A constant in wp-config.php takes precedence over an environment variable of the same name.

On multisite

A constant applies to every site in the network, and a site administrator cannot override it for their own site. Each site's own saved values stay in the database untouched, so removing the constant later restores what each site had chosen.

Value formats

Type	Accepted values	Example
Boolean	true, false, 1, 0, or the strings 'true', 'false', '1', '0'. Anything else, including 'yes' or 'on', is invalid.	define( 'EASY_MCP_AI_AUDIT_LOG_ENABLED', false );
Integer	A whole number within the setting's range.	define( 'EASY_MCP_AI_AUDIT_LOG_RETENTION', 90 );
List	A PHP array of strings, or one comma-separated string. Spaces around entries are ignored. An empty array or empty string clears the list.	define( 'EASY_MCP_AI_ALLOWED_TOOL_PATTERNS', 'wp_get_*, wp_list_*' );
Choice	One of the values listed for that setting, exactly as written.	define( 'EASY_MCP_AI_CHANGE_LOG_OPTION_MODE', 'allowlist' );
Text	A plain string.	define( 'EASY_MCP_AI_BRAND_NAME', 'Acme AI Connector' );

Environment variables are always strings, so write lists as comma-separated text and booleans as true or false.

What changes in the admin

When a setting is defined by a constant or an environment variable:

• Its field on the Easy MCP AI screens shows the effective value and is disabled. A small lock icon next to the description reads Managed in wp-config.php: EASY_MCP_AI_… or Managed by environment variable: EASY_MCP_AI_… on hover or keyboard focus.
• Saving the screen leaves the locked setting alone. The value from the constant is never written to the database, so removing the constant brings back whatever an administrator had saved before.
• Easy MCP AI → Dashboard lists every configuration-controlled setting and its source in a collapsed Deployment-controlled settings disclosure. The same list appears in the diagnostics report as the check named Deployment-controlled settings, which warns when a defined value is invalid.

The Disabled Tools list is one list for the whole plugin. When EASY_MCP_AI_DISABLED_TOOLS is defined, the per-provider tool switches on External Data and the switches on Plugin Integrations all show that list and are locked with it. There are no separate constants per provider.

Export the current settings

To turn the settings an administrator has already saved into define() lines, run:

wp easy-mcp-ai config export

On multisite, add --url=https://subsite.example.com to export one site's settings. The command prints the saved values, not the values currently active through constants, so it captures the choices you are about to lock in. It never prints credentials, API keys or the plugin's internal state.

Settings reference

The first column is the constant name; the environment variable has the same name. Each row names the admin field it locks.

General

Constant	Type and range	Default	Controls
EASY_MCP_AI_PAUSED	Boolean	false	Pause AI access on the Dashboard: when true, every AI client stays connected but sees no tools or resources, and each tool call is refused and recorded in the audit log. Unlike the other Boolean settings, an invalid value such as 'yes' pauses AI access instead of being ignored.
EASY_MCP_AI_RATE_LIMIT_PER_MINUTE	Integer, 1 to 1000	60	Rate Limit (per minute): tool calls allowed per token per minute.
EASY_MCP_AI_FORCE_DRAFT_ON_CREATE	Boolean	false	Force Draft on Create: new posts and pages are always saved as drafts, whatever status the AI client asked for.
EASY_MCP_AI_MAX_TITLE_LENGTH	Integer, 0 to 2000	0	Max Title Length: longest post or page title a tool accepts. 0 means no limit.
EASY_MCP_AI_AUDIT_LOG_ENABLED	Boolean	true	Audit Log: whether tool calls are recorded.
EASY_MCP_AI_AUDIT_LOG_RETENTION	Integer, 1 to 365	30	Audit Log Retention (days): older entries are removed daily.
EASY_MCP_AI_DISABLED_TOOLS	List of tool names	empty	Disabled Tools: tools that return an error when called, regardless of token permissions. Also locks the per-provider switches on External Data and Plugin Integrations.
EASY_MCP_AI_ALLOWED_TOOL_PATTERNS	List of glob patterns	empty	Whitelist Tools: when set, only tools whose names match a pattern such as wp_get_* are available, for every token.
EASY_MCP_AI_IP_WHITELIST	List of IP addresses or CIDR ranges	empty	IP Whitelist: addresses allowed to reach the MCP endpoint. Empty allows all. An invalid list refuses every request.
EASY_MCP_AI_OAUTH_MIN_CAPABILITY	publish_posts, edit_others_posts or manage_options	publish_posts	Minimum Capability to Authorize (OAuth): the WordPress capability a user needs to approve an AI client on the consent screen.
EASY_MCP_AI_EXTERNAL_DATA_MIN_CAPABILITY	publish_posts, edit_others_posts or manage_options	manage_options	The capability needed to use the Google Analytics, Search Console, DataForSEO, Semrush and SE Ranking tools.
EASY_MCP_AI_SELF_SERVICE_KEYS	Boolean	false	Self-service API keys: lets eligible users create and revoke their own API keys from their profile.
EASY_MCP_AI_SELF_SERVICE_MAX_KEYS	Integer, 1 to 1000	10	Active keys one user may hold under self-service. Configuration only, with no admin field.
EASY_MCP_AI_API_KEY_SITE_HOST	Host name or URL	empty	The host that API keys are bound to, when it should not be derived from the site address. Only needed on multi-domain or proxied setups where the WordPress home URL does not match the address clients use. Empty derives it from the site address.

OAuth

Constant	Type and range	Default	Controls
EASY_MCP_AI_OAUTH_ENABLED	Boolean	true	Whether the OAuth layer is available at all. When false, the registration, authorization and discovery endpoints are switched off and AI clients can connect only with API keys.
EASY_MCP_AI_OAUTH_ACCESS_TOKEN_TTL	Integer, seconds, at least 60	3600	Access Token TTL (seconds).
EASY_MCP_AI_OAUTH_REFRESH_TOKEN_TTL	Integer, seconds, at least 60	2592000	Refresh Token TTL (seconds).
EASY_MCP_AI_OAUTH_DCR_ENABLED	Boolean	true	Dynamic Client Registration: whether AI clients can register themselves for one-click sign-in. While it is off, no new client can be connected.
EASY_MCP_AI_OAUTH_MAX_CLIENTS	Integer, 0 or more	5000	The most registered OAuth clients the site accepts. Further registrations are refused once the cap is reached; 0 refuses every new registration.
EASY_MCP_AI_OAUTH_CLIENT_RETENTION	Integer, days, 0 to 3650	7	How long a client registration that was never used to sign in is kept before the daily cleanup removes it. 0 keeps them forever.
EASY_MCP_AI_OAUTH_ALLOW_HTTP	Boolean	false	Allows the OAuth endpoints over plain HTTP. Meant for local development behind a proxy; never enable it on a public site.

Change History

Constant	Type and range	Default	Controls
EASY_MCP_AI_CHANGE_LOG_ENABLED	Boolean	true	Change History: whether before-and-after snapshots of every write made through MCP are recorded.
EASY_MCP_AI_CHANGE_LOG_RETENTION	Integer, days, 0 or more	30	Change History Retention (days). 0 disables pruning.
EASY_MCP_AI_CHANGE_LOG_OPTION_MODE	all_except_denylist or allowlist	all_except_denylist	Option recording mode: record every option write except known churn, or only a fixed allowlist of core settings.
EASY_MCP_AI_CHANGE_LOG_CAPTURE_META	Boolean	true	Extended meta capture: term, user and comment meta plus network options.
EASY_MCP_AI_CHANGE_LOG_CAPTURE_DB	Boolean	false	Capture raw database writes: custom-table and direct SQL writes made during tool calls.
EASY_MCP_AI_CHANGE_LOG_DB_RETENTION	Integer, days, 0 or more	7	Raw-write retention (days). 0 disables pruning.
EASY_MCP_AI_CHANGE_LOG_DB_ROWS_PER_CALL	Integer, 0 or more	200	The most raw database rows recorded for one tool call. 0 removes the cap. Configuration only.
EASY_MCP_AI_CHANGE_LOG_EXTERNAL_INTENT	Boolean	true	Record external write intent: a marker row when a write-shaped tool call changed nothing locally but contacted a remote service.

Long-running tasks

These govern the MCP Tasks extension, which lets an AI client start a long-running ability and collect the result later. They are configuration only.

Constant	Type and range	Default	Controls
EASY_MCP_AI_TASKS_BACKGROUND	Boolean	true	Whether tasks advance in the background through WP-Cron or Action Scheduler. When false, a task only advances while its owner polls it.
EASY_MCP_AI_TASKS_TICK_BUDGET_SECONDS	Integer, 0 to 300	0	How long one background step may run. 0 derives the budget from PHP's execution time limit.
EASY_MCP_AI_TASKS_RETENTION_DAYS	Integer, 1 to 365	7	How long finished tasks are kept.
EASY_MCP_AI_TASKS_MAX_PER_CREDENTIAL	Integer, 1 to 100	5	Working tasks one API key or OAuth grant may have at once.
EASY_MCP_AI_TASKS_MAX_CONCURRENT_TICKS	Integer, 1 to 50	3	Background steps allowed to run at the same time across the site.

Proxies and site presentation

Constant	Covered in
EASY_MCP_AI_TRUSTED_PROXIES, CLIENT_IP_HEADER	Trusted Proxies
EASY_MCP_AI_HIDE_ADMIN, HIDE_PLUGIN_ROW, BRAND_NAME	White-Label and Hidden Admin

Credential hashing key

EASY_MCP_AI_TOKEN_KEYS is a constant or environment variable too, but it holds a secret rather than a setting, so it is deliberately kept outside the resolution above. It never appears in the Dashboard list, in the diagnostics report or in the export command. When set, API keys and OAuth tokens are stored as keyed hashes that cannot be recreated by someone with only database access.

openssl rand -hex 32

define( 'EASY_MCP_AI_TOKEN_KEYS', '<64 hexadecimal characters>' );

Each secret must be at least 32 bytes. To rotate, put the new secret first and keep the old one after it, separated by a comma; credentials issued before the change keep working until you remove the old secret. The diagnostics report shows which keys the site currently accepts. Credentials issued before a key was configured keep validating without one.

What cannot be set by constant

• Provider credentials for the External Data integrations (Google service accounts, DataForSEO, Semrush, Ahrefs, SE Ranking). These are saved, encrypted, from Easy MCP AI → External Data.
• API tokens and OAuth grants themselves.
• The plugin's internal state: schema versions, diagnostic caches and similar values it writes for itself.