headroom.walls.sh · mcp

Claude Code MCP setup

Configure Model Context Protocol servers in Claude Code — the mcpServers block in settings.json, transport types, scopes, and common examples.

What MCP gives Claude Code

Model Context Protocol (MCP) is how Claude Code talks to external tools and data sources beyond its built-in capabilities. An MCP server is a process (local or remote) that exposes tools, resources, and prompts. Claude Code calls these tools the same way it calls its own built-in tools — transparently, mid-session.

Common uses: read files outside the project tree, query databases, fetch GitHub issues, run browser automation, hit internal APIs, read Slack channels, manage calendar events.

Where to configure MCP

MCP servers go in the mcpServers block of settings.json. Two scopes:

Both files can have mcpServers. Claude Code merges them; project-level wins for the same server name.

mcpServers syntax

Each key in mcpServers is the server's display name. The value specifies how to launch it:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

Transport types

stdio fields

sse fields

Common MCP server examples

Filesystem (read files anywhere)

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

Gives Claude Code read/write access to /Users/you/Documents and below. Pass multiple paths as additional args.

GitHub

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Lets Claude Code read issues, PRs, and code from GitHub repos.

Postgres

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

Brave Search

{
  "mcpServers": {
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "..."
      }
    }
  }
}

Remote SSE server

{
  "mcpServers": {
    "internal-tools": {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse",
      "headers": {
        "Authorization": "Bearer ..."
      }
    }
  }
}

Custom local server (Python)

{
  "mcpServers": {
    "my-tools": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "DATABASE_URL": "sqlite:///~/data.db"
      }
    }
  }
}

Managing MCP servers at runtime

Inside any Claude Code session:

Server failures are shown inline when Claude Code tries to use a tool from a disconnected server — it won't silently skip them.

Scoping MCP to a project

Put project-specific servers (internal APIs, local scripts) in the repo's .claude/settings.json and commit it. Team members who clone the repo get the same MCP configuration. Keep credentials in environment variables, not in the committed file.

# .claude/settings.json (committed)
{
  "mcpServers": {
    "our-api": {
      "type": "stdio",
      "command": "node",
      "args": ["scripts/mcp-server.js"]
    }
  }
}

# .env (gitignored)
OUR_API_KEY=...

Adding the statusLineHook while you're in settings.json

The statusLineHook field lives alongside mcpServers in the same ~/.claude/settings.json. Once set, it writes your Claude Code session (5h) and weekly (7d) usage to a local file every status-line refresh — which is what Headroom reads to show your live usage in the menu bar.

{
  "statusLineHook": "cat ~/.claude/headroom-usage.json 2>/dev/null | jq -r '"CC \(.sessionUsagePct|floor)%·\(.weeklyUsagePct|floor)%"' 2>/dev/null || echo 'CC --%'",
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you"]
    }
  }
}

One file, two features: MCP tools + live usage display. No extra config.

Headroom shows your Claude Code session (5h) and weekly (7d) usage as a live % in the menu bar. Free, MIT, ~267 KB, signed + notarized.

brew install --cask patwalls/tap/headroom

→ Full settings.json reference
→ statusLineHook docs
→ Rate limits explained