Simpli WordPress MCP

A Railway-hosted, OAuth-protected remote MCP gateway for the WordPress Abilities API. It dynamically mirrors the existing Novamira and Novamira Pro abilities on one configured WordPress site instead of duplicating privileged WordPress code.

Verified scope

The Simpli Cosmetics production site was inspected on 12 August 2026. It currently exposes 187 REST abilities:

Namespace	Live abilities
novamira/*	157
rank-math/*	13
wpforms/*	8
woocommerce/*	7
core/*	2
Total	187

The mirrored surface includes:

• PHP execution in the loaded WordPress runtime;
• file read, write, edit, delete, enable/disable, and directory traversal;
• temporary upload links and one-time administrator access links;
• synchronous and background WP-CLI jobs;
• Gutenberg read/write and pending-change batches;
• WordPress posts, memory, and Markdown skills;
• WooCommerce products, variations, orders, categories, tags, attributes, stock, and store settings;
• Elementor documents, elements, styles, variables, classes, dynamic tags, and interactions;
• ACF field groups, values, post types, taxonomies, and options pages;
• Rank Math metadata, schema, audits, scores, links, keywords, and AI visibility;
• WPForms forms, fields, notifications, confirmations, settings, duplication, and statistics.

The gateway refreshes the catalog from WordPress every five minutes by default. New REST-exposed abilities installed later are automatically added to MCP with their original JSON input schema and safety annotations.

Architecture

flowchart LR
    C["ChatGPT / Codex"] -->|"OAuth 2.1 + MCP"| R["Railway gateway"]
    R -->|"Dedicated Application Password"| W["WordPress Abilities API"]
    W --> N["Novamira + Pro"]

Only the gateway is deployed to Railway. WordPress already contains Novamira, Novamira Pro, the MCP Adapter, and WP-CLI; no second control plugin is required.

Security model

• OAuth 2.1 Authorization Code flow with PKCE, dynamic client registration, protected-resource discovery, short-lived access tokens, and refresh tokens.
• A separate owner authorization password protects OAuth consent.
• A dedicated, revocable WordPress Application Password is stored only as a Railway secret.
• The target WordPress origin is fixed in server configuration; tools cannot redirect the gateway to an arbitrary host.
• WordPress remains the authority for each ability's permission callback and schema validation.
• Read, write, and dangerous scopes are enforced server-side.
• Novamira's PHP, WP-CLI, admin-link, and destructive abilities always require wordpress:dangerous and an exact _confirm value.
• MCP safety annotations are generated from the live WordPress annotations so clients can apply approval controls.
• Tool output is capped, request timeouts are enforced, redirects are rejected, credentials are never logged, and OAuth/MCP endpoints are rate-limited.
• Railway's /health endpoint is liveness only. /ready verifies that the WordPress ability catalog is available.

Local verification

Requirements: Node.js 22 or later.

npm ci
npm run check
npm test
npm run build

Copy .env.example to .env, fill the required values, then run:

npm run dev

Inspect http://localhost:3000/mcp with MCP Inspector using the optional MCP_STATIC_TOKEN as a Bearer token. Leave MCP_STATIC_TOKEN unset in the public production deployment unless a separate API integration specifically needs it.

Railway deployment

1. Create a dedicated WordPress administrator account for the gateway. Generate one Application Password named Railway Simpli MCP. Do not reuse a human password.

2. Create a Railway service from this repository or run railway up from this directory.

3. Add the variables shown in .env.example. Generate secrets locally:

   openssl rand -base64 48
   openssl rand -base64 48
   

4. Set PUBLIC_BASE_URL to the final HTTPS origin. If using a Railway-generated domain first, use that origin. If using mcp.simplicosmetics.co.ke, add it as a Railway custom domain and point the Cloudflare DNS record to the Railway target before changing this variable.

5. Confirm Railway reports /health as HTTP 200.

6. Open /ready; it must report ready: true and the expected ability count.

7. Add the complete /mcp URL as a remote MCP connection. The client will discover OAuth, dynamically register, and open the owner authorization page.

8. Run the acceptance checks in docs/ACCEPTANCE.md before enabling live write tools.

Railway injects PORT; the service listens on it automatically. The included railway.json configures Docker builds, /health, and restart-on-failure.

Operational rollback

Rollback is immediate and does not change WordPress code:

1. revoke the Railway Simpli MCP Application Password in WordPress;
2. pause or remove the Railway service;
3. remove its custom DNS record if one was created.

Existing Novamira functionality inside WordPress remains untouched.

Primary technical references

• WordPress Abilities API REST endpoints
• OpenAI: Build an MCP server
• OpenAI: MCP authentication
• Railway health checks
• Novamira capability overview