---
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