Skip to content

Troubleshooting and FAQ

xNetVN Development edited this page Nov 12, 2026 · 1 revision

Troubleshooting and FAQ

Most failures are the MCP dependency, an invalid key-authenticated request, or a key scope that does not admit the ability. Diagnose in that order. docs/user-guide.md is the checked configuration reference; docs/en/TROUBLESHOOTING.md lists the same HTTP error classes, but where details differ, follow the current source and user guide.

Useful screens are Agent Hub > Overview (endpoint, connection and authorization-header checks), Keys (state, scope, last use), Activity (outcome and reason) and Settings (enablement, ceiling, origins, proxies, limits). The management status route reports HTTPS, transport policy, adapter version/support, server creation, ability count and key count; it requires a cookie session and REST nonce (src/Rest/SettingsController.php).

1. Plugin is active but MCP is disabled

Symptom No usable MCP endpoint; the notice says the official MCP Adapter is required or outside the supported range. The plugin stays active.
Cause The adapter is absent, inactive, below 0.7.0 or at/above 0.8.0 (src/Bootstrap/Requirements.php).
Check Plugins screen: is the official MCP Adapter active? Overview/status: adapter.supported, adapter.version, adapter.server_created.
Fix Install and activate the official adapter inside >=0.7.0 <0.8.0. Do not bundle, fork or patch it. Also confirm Settings > Access > Enable the MCP server is on; when off, no server is created (src/Mcp/ServerGateway.php).

2. 401 or 403 on the MCP route

Symptom 401 with Authentication required, or 403 with a generic access message. The body does not reveal whether a key exists.
Cause 401: missing/malformed credential, unknown key, wrong secret, revoked or expired key, deleted owner. 403: owner lacks the use capability, IP outside an allowlist, site disabled, insecure transport, or origin denied (src/Auth/FailureReason.php).
Check Overview > Check Authorization header proves whether the web server forwards the header. Keys shows state and expiry. Activity shows auth_failed with the fixed reason. A cookie login is not an MCP credential.
Fix Send the key as a Bearer token in the approved header and ask the host to forward Authorization. Restore the owner's capability, replace an expired/revoked key, or correct the IP/site setting. For management screens, reload and log in again; management uses cookie plus nonce.

3. Origin is rejected

Symptom 403, Origin is not allowed.
Cause A browser sent an Origin outside the exact allowlist, sent null, or sent a malformed origin with a path, credentials, query or fragment. Site home/site URL origins are implicit; a missing Origin is allowed, which supports non-browser clients (src/Http/RouteGate.php, src/Http/OriginGuard.php).
Check Browser developer tools: the request Origin. Settings > Network > Additional allowed browser origins. Compare scheme, host and non-default port exactly.
Fix Add the exact scheme, host and port with no path. Use a non-browser client when no browser origin is needed. null and wildcards are not supported.

4. Rate limited

Symptom 429 with Retry-After, or a tool-level rate-limit error for a costly operation.
Cause More than 120 requests in the sliding minute for one key, more than 10 failed authentications per minute for one IP, or no free costly-operation slot (src/Persistence/WpSiteSettings.php).
Check Activity filtered to rate_limited; response Retry-After; Settings > Limits.
Fix Wait, apply backoff, and retry reads only. Never blindly retry a mutation; a repeated write can run twice. Raise a limit only after confirming correct client behavior.

5. Key revoked

Symptom 401 with the same generic message as any invalid credential.
Cause An owner or manager revoked the key, it expired, or its owner was deleted. Revocation is immediate (src/Auth/KeyService.php).
Check Keys filtered by state: revoked_at, expiry and last use. Activity shows auth_failed for that key.
Fix Create a replacement with the intended scope and update the client. A revoked key cannot be restored or edited. If unexpected, review Activity before reissuing.

6. HTTPS is refused

Symptom 403, A secure transport is required.
Cause WordPress does not see TLS, or a proxy asserts TLS without a trusted X-Forwarded-Proto, or the proxy peer is outside the trusted CIDR (src/Http/TransportGuard.php).
Check Status: https, transport_allowed. Settings > Network > Trusted TLS proxy header names and Trusted proxy IP networks.
Fix Serve over HTTPS. If TLS terminates at a proxy, allow only X-Forwarded-Proto and list the proxy CIDR. The local exemption is limited to the local or development environment and an explicit constant; it is not a production switch.

7. Adapter hook mismatch

Symptom The adapter reports a supported version, but no MCP server is created; the endpoint is missing or returns a server-configuration error.
Cause The installed adapter lacks the expected create_server API or hook signatures, or creation failed. Verification covers only the official 0.7.x line (docs/en/architecture/adapter-notes.md).
Check Status: adapter.supported versus adapter.server_created. If supported is true, server_created false and the site is enabled, suspect the adapter build or load-order conflict.
Fix Replace it with the official release in range and retry. Do not add shims outside Mcp/ServerGateway; that facade is the only permitted adapter boundary. Capture the version and status response without credentials.

8. Multisite scope confusion

Symptom A key that works on one site returns 401 on another; tools or settings differ.
Cause Keys, settings, audit rows and the pepper are per site. A key from site A does not exist on site B. Super administrators keep default use and management, but each site's role matrix, settings and policy still apply (docs/en/architecture/overview.md).
Check Confirm the current site in the admin bar. Open Keys, Settings and Activity on the target site, not only the network screen.
Fix Create a key on each site where the client connects, with that site's scope. Configure ceiling, roles, origins and limits per site. Network-wide deactivation clears events but does not merge data.

See Configuration for the settings behind these checks, Key-Management for credential lifecycle, and Audit-and-Logging for evidence collection.

FAQ

Does a logged-in cookie work for MCP? No. MCP accepts only a bearer key; cookies and Application Passwords are rejected there. Management is the opposite: cookie plus nonce (docs/en/FAQ.md).

Can I use one key across a Multisite network? No. Keys and the pepper are per site; create one per site.

Can I recover a lost key? No. The plaintext is shown once and only a digest is stored. Rotate or create a replacement.

Does a role change take effect immediately? Yes, on the next request. Capabilities are resolved live, not from a snapshot (docs/en/adr/0005-capability-intersection.md).

Why does tools/list show fewer tools than exist? Listing is filtered by policy: key tier, toolsets, allow/deny lists, site ceiling and owner capabilities (src/Mcp/ServerGateway.php).

Does the activity log store prompts or outputs? No. It stores metadata and top-level argument names only (docs/en/adr/0010-minimal-audit.md).

Clone this wiki locally