fcecde0de4
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 2s
Removed cognitive-memory MCP, timers, and symlink system references. Replaced with kb-search MCP and /save-doc skill workflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
---
|
|
title: "Claude Code Configuration"
|
|
description: "Reference for Claude Code config file locations and precedence, MCP server setup in ~/.claude.json, hooks, permissions, and common gotchas."
|
|
type: reference
|
|
domain: workstation
|
|
tags: [claude-code, mcp, config, hooks, permissions, claude]
|
|
---
|
|
|
|
# Claude Code Configuration
|
|
|
|
## Config File Locations
|
|
|
|
Claude Code reads settings from multiple files in a specific precedence order:
|
|
|
|
| File | Scope | What goes here |
|
|
|------|-------|---------------|
|
|
| `~/.claude.json` | User-level (all projects) | MCP servers, startup state, git repo mappings |
|
|
| `~/.claude/settings.json` | User-level (all projects) | Permissions, hooks, env vars, plugins, status line |
|
|
| `~/.claude/projects/<sanitized-cwd>/settings.json` | Project-level | Project-specific permission overrides |
|
|
| `<repo>/.claude/settings.json` | Repo-level (checked in) | Shared team settings |
|
|
| `<repo>/.mcp.json` | Repo-level (checked in) | Project-scoped MCP servers |
|
|
|
|
**Important**: `~/.claude.json` (home directory root) is different from `~/.claude/settings.json` (inside the `.claude` directory). They serve different purposes.
|
|
|
|
## MCP Server Configuration
|
|
|
|
MCP servers are defined in the top-level `mcpServers` key of `~/.claude.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"server-name": {
|
|
"command": "/path/to/binary",
|
|
"args": ["-t", "stdio"],
|
|
"env": {
|
|
"API_KEY": "value"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Server Types
|
|
|
|
**stdio** — local process, communicates over stdin/stdout:
|
|
```json
|
|
{
|
|
"command": "/path/to/binary",
|
|
"args": ["--flag", "value"],
|
|
"env": { "KEY": "value" }
|
|
}
|
|
```
|
|
|
|
**http** — remote HTTP server (Streamable HTTP transport):
|
|
```json
|
|
{
|
|
"type": "http",
|
|
"url": "http://host:port/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer <token>"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Current MCP Servers
|
|
|
|
All defined in `~/.claude.json` under `mcpServers`:
|
|
|
|
| Server | Type | Purpose |
|
|
|--------|------|---------|
|
|
| `n8n-mcp` | stdio | n8n workflow automation API |
|
|
| `gitea-mcp` | stdio | Gitea API (issues, PRs, repos) |
|
|
| `tui-driver` | stdio | TUI automation for testing |
|
|
| `kb-search` | url | Knowledge base semantic search (manticore) |
|
|
|
|
### Managing MCP Servers
|
|
|
|
- **Add interactively**: `/mcp add <name>` in Claude Code (stores in `~/.claude.json`)
|
|
- **Add manually**: Edit the `mcpServers` object in `~/.claude.json`
|
|
- **Reconnect**: `/mcp` → select server → Reconnect (useful after remote server restarts)
|
|
- **Permissions**: Auto-allow MCP tools via `"mcp__server-name__*"` in `~/.claude/settings.json` permissions.allow
|
|
|
|
### Gotchas
|
|
|
|
- **Session drops**: Remote (url) MCP servers lose their session if the server container restarts. Run `/mcp` to reconnect.
|
|
- **Don't confuse config files**: `~/.claude.json` holds MCP servers. `~/.claude/settings.json` holds permissions/hooks. They are NOT the same file.
|
|
- **Stale configs**: `~/.claude/.mcp.json` and `~/.claude/.mcp-full.json` are NOT read by Claude Code despite looking like they should be. The canonical location is `~/.claude.json`.
|
|
|
|
## Hooks
|
|
|
|
Hooks are configured in `~/.claude/settings.json` under the `hooks` key. They run shell commands or HTTP requests in response to events.
|
|
|
|
### Current Hooks
|
|
|
|
| Event | Action |
|
|
|-------|--------|
|
|
| `PostToolUse` (Edit/Write/MultiEdit) | Auto-format code via `format-code.sh` |
|
|
| `SubagentStop` | Notify via `notify-subagent-done.sh` |
|
|
|
|
## Permissions
|
|
|
|
Permission rules live in `~/.claude/settings.json` under `permissions.allow` and `permissions.deny`. Format: `ToolName(scope:pattern)`.
|
|
|
|
Common patterns:
|
|
- `"mcp__gitea-mcp__*"` — allow all gitea MCP tools
|
|
- `"WebFetch(domain:docs.example.com)"` — allow fetching from specific domain
|
|
- `"Bash(ssh:*)"` — allow SSH commands
|