Repository navigation
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).
| 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). |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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.
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).
xNetVN Agent Hub WP · GPL-2.0-or-later · Copyright (c) 2026 xNetVN Inc.
This wiki summarizes the repository documentation. The source of truth is the repository; when they disagree, the repository wins.
Start here
Using the plugin
Security
Engineering
Project