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
• Switch single tools on or off
• Credential hashing key
• External Data provider credentials
• 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 → Settings 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.

EASY_MCP_AI_DISABLED_TOOLS remains a plugin-wide deployment restriction. Ordinary tool enablement is managed in Easy MCP AI > Tools, where deployment-controlled choices are locked; the old Settings > Advanced > Disabled tools grid is no longer present. There are no separate disabled-tool constants per provider.

Deployed approval settings take precedence over saved per-tool Require approval choices. Their constants remain supported even though the former global approval fields are no longer on the Settings screen.

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	120	Rate Limit (per minute): tool calls allowed per credential 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	Deployment restriction blocking listed tools regardless of token permissions; manage ordinary saved tool choices in Tools.
EASY_MCP_AI_ALLOWED_TOOL_PATTERNS	List of glob patterns	empty	Deployment allowlist: when set, only matching tool names are available. This is not an editable Whitelist Tools field in the current Settings screen.
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	Roles that can connect an AI client: the WordPress capability a user needs to approve an AI client (on the consent screen or the device login page) and to use self-service API keys. Administrators can always connect. Defining it locks the checklist, and roles ticked there are ignored until EASY_MCP_AI_CONNECT_ROLES is defined as well.
EASY_MCP_AI_CONNECT_ROLES	List of role slugs	empty	Roles that can connect an AI client: extra roles, such as contributor, whose users can connect even though they do not hold the capability above. Slugs that are not roles on the site are ignored. Defining it locks the checklist.
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_HEADER_ONLY	Boolean	false	Accepts API keys only in the Authorization header. When true, a key sent in the endpoint URL, in an api_key query parameter or in the request body is refused with HTTP 401, even if the same request also carries a valid header. OAuth connections are not affected. Configuration only, with no admin field. Like EASY_MCP_AI_PAUSED, an invalid value such as 'yes' switches it on. See Keep API keys out of URLs.
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.
EASY_MCP_AI_SKILLS_SYNC	Boolean	true	Whether the plugin downloads updated skills from skills.easymcpai.com once a day after an AI client has connected. When false, the skills bundled with the plugin are served. Configuration only, with no admin field. Unlike the other Boolean settings, an invalid value such as 'yes' turns the download off. See Manage the Skills Easy MCP AI Serves.

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_CIMD	Boolean	true	Allows OAuth clients to use Client ID Metadata Documents. Configuration only, with no admin field; an invalid value switches support off. Clients using metadata documents also require Dynamic Client Registration.
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

Switch single tools on or off

EASY_MCP_AI_TOOLS switches individual tools on or off by name, for example define( 'EASY_MCP_AI_TOOLS', 'wp_delete_user=off,wp_privileged_files_read_query=on' );. It is the way to switch on a privileged tool from code, and with a *=off entry it keeps every tool a later update adds switched off until you name it. It is read only from wp-config.php or the environment, so it never appears in the Dashboard list or in the export command. See Switch Tools On or Off from wp-config.php for the format and examples.

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.

External Data provider credentials

You can provide External Data credentials with a PHP constant or an environment variable. For each credential below, the environment variable has the same name as the constant, and a PHP constant takes precedence over an environment variable with that name.

Provider	PHP constant	Environment variable
Google Analytics 4	EASY_MCP_AI_GA_SERVICE_ACCOUNT_JSON	EASY_MCP_AI_GA_SERVICE_ACCOUNT_JSON
Google Search Console	EASY_MCP_AI_GSC_SERVICE_ACCOUNT_JSON	EASY_MCP_AI_GSC_SERVICE_ACCOUNT_JSON
DataForSEO login	EASY_MCP_AI_DFS_LOGIN	EASY_MCP_AI_DFS_LOGIN
DataForSEO API password	EASY_MCP_AI_DFS_API_PASSWORD	EASY_MCP_AI_DFS_API_PASSWORD
Semrush	EASY_MCP_AI_SEMRUSH_API_KEY	EASY_MCP_AI_SEMRUSH_API_KEY
SE Ranking	EASY_MCP_AI_SERANKING_API_KEY	EASY_MCP_AI_SERANKING_API_KEY
Ahrefs	EASY_MCP_AI_AHREFS_API_KEY	EASY_MCP_AI_AHREFS_API_KEY

For example, define a key in wp-config.php or set the environment variable with the same name:

define( 'EASY_MCP_AI_SEMRUSH_API_KEY', 'replace-with-your-api-key' );

EASY_MCP_AI_SEMRUSH_API_KEY=replace-with-your-api-key

Each provider uses its deployment credentials as a provider-wide setup rather than combining them with credentials saved in the database. If a required deployment value is missing, empty, or invalid, that provider is unavailable; it does not fall back to its saved credentials. For DataForSEO, provide both the login and API password or neither. Google credentials must contain the raw service-account JSON, not a file path.

Credentials saved in the database are retained while deployment credentials are in use. Remove all deployment credentials for a provider to restore its saved setup.

In Easy MCP AI > Tools, open External data and select Connections. Deployed credentials are identified by constant name instead of being shown as editable secrets. The regular credential form is used when deployment credentials are not set; the image below illustrates that database-backed setup.

What cannot be set by constant

• API tokens and OAuth grants themselves.
• The plugin's internal state: schema versions, diagnostic caches and similar values it writes for itself.