Skip to content
WP EngineDocumentation

MCP server (Streamable HTTP transport)

POST
/v1/mcp
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/mcp', [
  'body' => '{ "jsonrpc": "2.0", "id": "example", "method": "initialize", "params": { "protocolVersion": "example", "capabilities": {}, "clientInfo": { "name": "example", "version": "example" } } }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Exposes the gateway as a remote MCP server over the Streamable HTTP transport (JSON-RPC 2.0 over HTTP, optionally upgrading to Server-Sent Events for streamed responses). Accepts either a WP Engine API key (prefixed “wpe_”) carrying the mcp scope, scoped to the key’s project, or an Okta JWT with WPEngine-Account and WPEngine-Project headers (Console Coworker). Interactive OAuth sign-in for external MCP clients (e.g. Claude Desktop) is planned. The gateway does not preserve MCP session state between requests; clients should not rely on server-side session continuity across calls. The list_site_abilities, search_abilities, and run_site_ability tools additionally require a personal API key when using API-key auth; a project-scoped key resolves no acting user and these tools return an unauthorized error. Okta JWT callers use the verified subject instead. For run_site_ability, a timed-out read returns the tool error code timeout, including when WordPress reports an upstream timeout with a REST 504 response. Any WordPress error code and message are retained in the tool error message. Retrying the identical read is safe. An uncertain write returns ambiguous_outcome and must not be retried automatically.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
WPEngine-Account
string

WP Engine account context. For API keys the account acted on is derived from the key and this header is informational only. For Okta JWT (Console Coworker) this header is required and must match the token’s account claim.

WPEngine-Project
string

WP Engine project context. Required for Okta JWT callers (Console Coworker). For API keys the project is derived from the key.

Agent-Session-Id
string

Optional. The agent session a knowledge-base tool call is being performed for, when the call answers a tool request from that session. Used only to group the call with the rest of the session’s activity in observability data. It is ignored unless it names a session in the same project as the caller, and it never changes the response.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
One of: discriminator: method

JSON-RPC request initiating the MCP session handshake.

object
jsonrpc
required
string
Allowed values: 2.0
id
required
One of:
string
method
required
string
Allowed values: initialize
params
required
object
protocolVersion
required

MCP protocol version the client supports, e.g. “2025-06-18”.

string
capabilities
required

Client-declared capabilities (roots, sampling, elicitation, etc.) per the MCP spec.

object
key
additional properties
any
clientInfo
required

Name and version of an MCP client or server implementation.

object
name
required
string
version
required
string

Responses

Section titled “Responses”

200

Section titled “200”

One application/json JSON-RPC response for a single request, or an array of responses when the POST body was a JSON-RPC batch.

Media typeapplication/json
One of:

JSON-RPC 2.0 success response. result’s shape depends on the request’s method — see McpInitializeResult, McpPingResult, McpListToolsResult, and McpCallToolResult.

object
jsonrpc
required
string
Allowed values: 2.0
id
required
One of:
string
result
required
One of:

Result of an initialize request.

object
protocolVersion
required
string
capabilities
required

Server-declared capabilities. This server advertises tools only — no resources, prompts, sampling, or roots.

object
key
additional properties
any
serverInfo
required

Name and version of an MCP client or server implementation.

object
name
required
string
version
required
string
instructions

Optional human-readable usage instructions from the server.

string
Example
{
  "jsonrpc": "2.0"
}

202

Section titled “202”

Accepted with no body for JSON-RPC notifications (such as notifications/initialized) that do not expect a response.

400

Section titled “400”

Invalid MCP request — for example, a missing or invalid Accept header, an empty POST body, a JSON-RPC batch exceeding 10 messages, or malformed JSON-RPC payload. Oversized batches return HTTP 400 with a JSON-RPC Invalid Request error (code: -32600, message: batch exceeds maximum of 10 calls) before any message is dispatched. Most other validation failures return plain text; MCP standard header mismatches return a JSON-RPC error object instead.

string

401

Section titled “401”

Missing or invalid bearer token

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Headers

Section titled “Headers”
WWW-Authenticate
string
Example
Bearer realm="ai-services"

403

Section titled “403”

The token is valid, but the request is forbidden. Error type “permission_error” means the token’s scope/permission is insufficient or the authenticated user is not authorized for the target account; “entitlement_required” means the account lacks the required product entitlement; and “account_required” means no billing account could be resolved. On /v1/chat/completions when content moderation is enabled, and on /v1/sessions/{session_id}/events, error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

415

Section titled “415”

Request Content-Type is not application/json.

Media typetext/plain
string

503

Section titled “503”

A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off. An entitlement lookup failure uses error type “entitlement_unavailable”.

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}