67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
---
|
|
title: "Fix: kb-search MCP server 'needs authentication' after server restart"
|
|
description: "Claude Code shows OAuth errors connecting to kb-search MCP after ubuntu-manticore restart. Fix involves reconfiguring with bearer token headers and clearing stale OAuth credentials."
|
|
type: troubleshooting
|
|
domain: docker
|
|
tags: [troubleshooting, kb-rag, claude-code, docker, manticore]
|
|
---
|
|
|
|
# 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:
|
|
|
|
1. **Stale MCP session:** The server restart invalidated all existing MCP sessions. Claude Code clients got "Session not found" errors on reconnect.
|
|
|
|
2. **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
|
|
|
|
1. **Reconfigure MCP with bearer token header** (user scope so it applies globally):
|
|
```bash
|
|
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).
|
|
|
|
2. **Remove stale OAuth credential** from `~/.claude/.credentials.json`:
|
|
```python
|
|
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)
|
|
```
|
|
|
|
3. **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
|