Fix: kb-search MCP server 'needs authentication' after server restart

Date: 2026-03-25 Severity: Medium — kb-search MCP unavailable across all Claude Code sessions

Problem

After restarting ubuntu-manticore (crash recovery), the kb-search MCP server showed "needs authentication" in Claude Code's /mcp panel. Error message:

Error: HTTP 404: Invalid OAuth error response: SyntaxError: JSON Parse error: Unexpected EOF. Raw body:

The server was healthy (/health returned OK) but Claude Code was attempting OAuth discovery against a server that only supports static bearer token auth.

Root Cause

Two issues compounded:

Stale MCP session: The server restart invalidated all existing MCP sessions. Claude Code clients got "Session not found" errors on reconnect.
Stale OAuth credential: Claude Code had a cached OAuth entry in ~/.claude/.credentials.json under the mcpOAuth key (kb-search|120dc71b28e46913). This entry caused Claude Code to attempt OAuth discovery (hitting /.well-known/oauth-authorization-server) instead of using the static Authorization: Bearer header from the MCP config. The server returned 404 on the OAuth endpoint, which Claude Code couldn't parse.

The stale OAuth entry persisted even after reconfiguring the MCP server with correct headers config — mcpOAuth credentials override static headers.

Fix

Reconfigure MCP with bearer token header (user scope so it applies globally):

claude mcp remove kb-search
claude mcp add-json kb-search \
  '{"type":"http","url":"http://10.10.0.226:8001/mcp","headers":{"Authorization":"Bearer <token>"}}' \
  --scope user

Token is in ~/docker/md-kb-rag/.env on manticore (MCP_BEARER_TOKEN value).

Remove stale OAuth credential from ~/.claude/.credentials.json:

import json
f = '/home/cal/.claude/.credentials.json'
d = json.load(open(f))
oauth = d.get('mcpOAuth', {})
keys = [k for k in oauth if 'kb-search' in k]
for k in keys:
    del oauth[k]
d['mcpOAuth'] = oauth
with open(f, 'w') as fh:
    json.dump(d, fh, indent=2)

Restart Claude Code to establish a fresh MCP connection.

Lessons

Stale mcpOAuth entries in .credentials.json take priority over static headers config — always check and clear these when MCP auth issues occur
After any server hosting MCP endpoints restarts, all Claude Code sessions need restart to reconnect
The --scope user flag on claude mcp add-json is essential — without it, config goes to project-local and won't appear in other projects
kb-rag uses bearer token auth, NOT OAuth — if Claude Code shows OAuth errors for this server, the config is wrong

3.1 KiB Raw Blame History

Fix: kb-search MCP server 'needs authentication' after server restart

Problem

Root Cause

Fix

Lessons

3.1 KiB

Raw Blame History