MCP Server always returns "Invalid or missing API token" (code -32001), for every token, on every auth method

[streamevent-bg]

MCP Server always returns "Invalid or missing API token" (code -32001), for every token, on every auth method

Panopticon version: 2.2.0 (Daybreak), released 2026-07-03
PHP version: 8.3.31
Server: Apache (shared hosting, SuperHosting.BG)

Summary

After enabling the MCP server (System Configuration → Security → MCP Server) and minting an API token, every request to the MCP endpoint is rejected with:

{"error":{"code":-32001,"message":"Invalid or missing API token."}}

This happens regardless of token, transport, or client — I've ruled out every client-side explanation I could think of.

What I tried (all fail identically)

1. Three independent API tokens, created at different times, via different methods:
   • Token created via the admin UI by me (as the account owner)
   • Token created via my own browser session with zero automation involved
   • All three: same user (Super User), default "all scopes" (no scopes explicitly checked)
2. Both documented endpoint forms:
   • https://panopticon.example.com/mcp → 404 (no mod_rewrite rule for /mcp in .htaccess, so I used the form below instead)
   • https://panopticon.example.com/index.php/mcp → reaches the MCP server correctly (confirmed by the exact JSON-RPC error shape and the WWW-Authenticate: Bearer realm="Panopticon MCP" header)
3. Both documented authentication methods:
   • Authorization: Bearer YOUR_API_TOKEN header
   • ?_panopticon_token=YOUR_API_TOKEN query parameter (the documented fallback for clients without header support)
4. Multiple clients, to rule out any client-specific bug:
   • Raw PHP file_get_contents() with a manual stream context (server-side, via SSH — hit an unrelated 421 Misdirected Request SNI self-loopback issue when calling the site's own hostname from itself, so this path is inconclusive on its own)
   • A real external client: browser fetch() / direct navigation from an entirely separate network (not the hosting server) — same -32001 error, both with the header and with the query parameter
   • mcp-remote bridging Claude Desktop (ran into unrelated OAuth-discovery behavior, not the root cause)
   • supergateway bridging Claude Desktop (--streamableHttp <url> --oauth2Bearer <token>) — sends a clean, correctly-headered POST request; still -32001

The last two points are the important ones: a plain external HTTP client, hitting the real public endpoint, with a token the account owner just minted and copy-pasted himself, gets the exact same rejection as every other attempt. This rules out header-stripping, SNI/proxy issues, OAuth-discovery bugs in a particular MCP client, and token transcription errors.

Request/response example

[streamevent-bg]

Here continues:
POST /index.php/mcp?_panopticon_token=REDACTED HTTP/1.1
Host: panopticon.example.com
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

Response:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Panopticon MCP"
Content-Type: application/json; charset=utf-8
{"error":{"code":-32001,"message":"Invalid or missing API token."}}

Expected behavior

A freshly-minted, unscoped (all-scopes) API token belonging to a Super User should authenticate successfully against the MCP server's initialize method, exactly as it does against the JSON API at /api/* (I have not yet verified whether the same token works against /api/* — happy to test if useful).

Additional context

• The MCP server was confirmed enabled (toggle on, saved) in System Configuration → Security → MCP Server.
• The install completed the standard CLI setup (config:create, database:update, user:create, config:maxtime:test, config:set finished_setup true) without issue, and the site is otherwise fully functional (one Joomla site registered and monitored correctly, CRON running every minute, JSON API not yet tested).
• Happy to provide further diagnostics (PHP error log excerpts, DB inspection of the api_tokens table, etc.) if that would help pin this down.

[nikosdion]

Thanks for the exceptionally thorough report — the diagnostics you gathered (external client, both transports, the WWW-Authenticate header confirming you reached the MCP controller) let me pin this down quickly. You've hit three separate issues, and none of them are your fault. All three are now fixed in commit 9c7291d, shipping in 2.2.1.

1. The Authorization header is being stripped before it reaches PHP (this is your 401).
Panopticon's token auth read the header only from $_SERVER['HTTP_AUTHORIZATION'], which on Apache/PHP-FPM is populated solely by the SetEnvIf Authorization … directive in the shipped .htaccess. On a host where that directive doesn't take effect (mod_setenvif disabled, restricted AllowOverride, or the request not going through the .htaccess), the header silently never arrives and every Bearer request fails — API and MCP alike. The fix adds a getallheaders() fallback so the header is recovered regardless.

2. https://…/mcp returns 404 because htaccess.txt shipped with an api rewrite rule but no mcp one, so /mcp was a plain filesystem 404. Fixed by adding the mirroring rewrite rule.

3. The ?_panopticon_token= fallback is corrupted for many tokens. API tokens are Base64 and frequently contain +, which a URL decodes to a space. The fix restores the space back to + server-side.

Confirm the diagnosis (30 seconds)

Each failed attempt is logged. Please run:

SELECT occurred_on, JSON_EXTRACT(details, '$.reason') AS reason
FROM   pnptc_audit_log
WHERE  action = 'apitoken.auth_failure'
ORDER BY occurred_on DESC
LIMIT 10;

A reason of missing_token confirms issue #1 (header stripping); invalid_token would point at #3. That tells us definitively which one bit you.

Please try the fix on your install

Rather than wait for 2.2.1, you can drop the fixed files straight onto your installation from commit 9c7291d:

1. Replace src/Library/Api/TokenAuthentication.php with the version from that commit — this alone should fix your 401 (it adds the getallheaders() fallback and the query-param repair). Raw file: https://raw.githubusercontent.com/akeeba/panopticon/9c7291d/src/Library/Api/TokenAuthentication.php
2. Replace htaccess.txt with the version from that commit and re-copy it to .htaccess — this makes the short /mcp URL work. (If you're happy staying on /index.php/mcp, you can skip this one.)

No cache clear or DB change is needed. After step 1, retry initialize against /index.php/mcp with your Bearer token and let me know if it authenticates.

Also fixed

The documentation now uses /index.php/mcp as the canonical endpoint and covers Authorization-header forwarding for Apache, Nginx, and IIS.

Could you also post the audit-log output above so I can confirm #1 was the culprit on your host? Thanks again for the great report.

[streamevent-bg]

Thank you for the fast and precise diagnosis — much appreciated.

Audit log confirmation

occurred_on           reason
2026-07-05 06:29:50   "missing_token"
2026-07-04 20:12:47   "missing_token"
2026-07-04 20:12:26   "missing_token"
2026-07-04 20:11:24   "missing_token"
2026-07-04 20:09:57   "missing_token"

Consistently missing_token — confirms issue #1 (header stripping) was the culprit on this host, as you suspected.

Applying the fix uncovered two host-specific issues, one of which may be worth documenting

I replaced src/Library/Api/TokenAuthentication.php with the version from commit 9c7291d and retested. It didn't authenticate — turns out there are two separate things going on, neither of which is a problem with your patch:

1. Authorization never reaches PHP at all on this host, at any layer.

This install runs PHP via cgi-fcgi (confirmed via php_sapi_name()), not mod_php. I dropped a small diagnostic script in the site root that checked $_SERVER['HTTP_AUTHORIZATION'], getallheaders(), and apache_request_headers() directly. All three came back empty for Authorization — but a custom header (X-Panopticon-Token) sent in the same request arrived just fine. So on this particular Apache/FastCGI setup, the Authorization header is being stripped before PHP starts (no CGIPassAuth / effective SetEnvIf, likely due to hosting-level AllowOverride restrictions), which means getallheaders()/apache_request_headers() can't recover it either — there's nothing in the FastCGI env for them to read. The fix in 9c7291d is correct and will help hosts where the header does reach $_SERVER in some non-HTTP_AUTHORIZATION form, but it can't help here since the header never arrives in any form. Good news: switching our client config to send X-Panopticon-Token instead of Authorization: Bearer worked immediately once combined with fix #2 below — might be worth a callout in the docs for shared-hosting users on cgi-fcgi/LSPHP setups, since I'd guess we're not the only ones behind this exact configuration.

2. Separate, install-specific bug: secret was never generated in config.php.

Even with the header arriving correctly (via X-Panopticon-Token), auth still failed — this time with reason no_secret. I checked config.php directly: the secret property isn't just empty, it's entirely absent from the class — not one of the ~113 declared public properties. The CLI setup script we ran (config:create, database:update, user:create, config:maxtime:test, config:set finished_setup true) apparently never populated it. Since Apitoken::computeToken() hashes against $this->container->appConfig->get('secret', ''), every token — old or new — was unconditionally rejected as long as that key stayed empty/missing, regardless of the header issue.

I fixed this locally by adding public $secret = '<64 random hex chars>'; directly to config.php and generating a fresh API token afterward (the old ones were computed against a nonexistent secret and can never validate). This worked. But it seems like config:create should always generate and persist a secret value on install — might be worth checking whether there's a code path where that step can silently no-op (e.g. re-running config:create on an already-initialized install, or a specific CLI flag combination). Happy to share the relevant section of config.php (with the actual secret redacted) if it'd help pin down the code path.

End state (working)

For anyone hitting the same combination on shared hosting:

{
  "mcpServers": {
    "panopticon-yoursite": {
      "command": "npx",
      "args": [
        "-y", "supergateway",
        "--streamableHttp", "https://panopticon.example.com/index.php/mcp",
        "--header", "X-Panopticon-Token: YOUR_API_TOKEN"
      ]
    }
  }
}

Confirmed working end-to-end with a real initialize call (200, valid MCP handshake, serverInfo returned correctly).

Thanks again for the responsiveness on this — let me know if the config.php snippet would help track down the missing-secret path.

[nikosdion]

Brilliant follow-up — the cgi-fcgi diagnostic and the no_secret audit-log reason let me pin down both remaining issues precisely. Both are now fixed in commit 192c59f (shipping in 2.2.1), and I've reproduced your exact failure end-to-end against a throwaway install to confirm the fix.

1. X-Panopticon-Token — you found the right answer, and it's now documented

You're correct: when the host strips Authorization before PHP starts (as cgi-fcgi/LSPHP with a restricted AllowOverride does), nothing on the PHP side — $_SERVER, getallheaders(), apache_request_headers() — can recover it. The X-Panopticon-Token custom header is the right fallback because such setups forward it untouched. Your supergateway config is an excellent, practical demonstration, so I've added it (generalised) straight into the docs:

• MCP Server → Alternative: the X-Panopticon-Token header — including the supergateway mcpServers snippet you shared.
• API Overview now calls out X-Panopticon-Token as the reliable fallback for cgi-fcgi/LSPHP hosts.

2. The missing secret — confirmed, and it's a real bug (not specific to your host)

You nailed it. I traced it and reproduced it deterministically:

• config.php only ever receives a secret when the bootstrap transcribes it from tmp/secret.php. That transcription required an internal flag (self::$secret) that was set only when the secret was freshly generated — not when the bootstrap adopted an already-existing tmp/secret.php. So whether the secret ended up in config.php came down to a timing race on the tmp/secret.php lifecycle. Neither config:create nor the web installer wrote a secret directly.
• With secret empty, the no_secret guard (added with the JSON API) rejects every token, exactly as your audit log showed.

Three fixes in 192c59f:

1. The bootstrap now adopts the existing tmp/secret.php secret into that flag, so the transcription into config.php fires reliably — and self-heals existing installs like yours on the very next request.
2. tmp/secret.php is now deleted only after the secret is successfully persisted (so read-only .env/containerised installs, which can't save, keep it stably instead of regenerating a new secret every request).
3. config:create now generates and persists a secret directly, so a CLI-created config.php is always self-contained from the first request.

Note on your existing tokens: as you discovered, tokens minted while the secret was empty were computed against an empty secret and can never validate once a real secret is in place. After upgrading (or applying the fix below), re-mint your tokens — which you've already done. 👍

Try it now, without waiting for 2.2.1

Replace src/Application/BootstrapUtilities.php with the version from commit 192c59f:
https://raw.githubusercontent.com/akeeba/panopticon/192c59f/src/Application/BootstrapUtilities.php

On the next page load the bootstrap will transcribe the secret from tmp/secret.php into your config.php automatically (you can confirm public $secret = '…'; appears in config.php afterwards, and tmp/secret.php is removed). Then re-mint a token and it will authenticate. If for any reason tmp/secret.php is gone, a fresh secret is generated and persisted instead — either way config.php ends up self-contained.

Thanks again for the thorough diagnostics and for confirming the working end state — the supergateway example in particular will help other shared-hosting users.