# Optimizing Claude Code

> The MCP servers and plugins that make Claude Code sharper - Serena for symbolic code intelligence, plus live docs, the open web, a real browser, and secrets that never touch a config file.

Claude Code out of the box reads files and greps. Every tool below hands it a
sharper instrument: a language server, live documentation, a browser, the open
web. This is the exact setup running on my machine - every block is
copy-pasteable, and every tool links back to the project that built it. All
credit belongs upstream.

One rule before any of it: register MCP servers with `--scope user`, so they
live in your user config and follow you into every repo. A server bolted onto
one project is a server you will miss in the next one.

## 1. Serena - symbolic code intelligence

The main thing. [Serena](https://github.com/oraios/serena) is an MCP server
that wraps real language servers and gives the agent _symbol_ tools: get an
overview of a file's symbols, jump to a definition, find every reference,
replace one function body. Instead of grepping and reading whole files into
context, Claude navigates the code the way an IDE does - which is both more
precise and dramatically cheaper in tokens on a large codebase.

```bash
claude mcp add serena --scope user -- \
  uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context claude-code --project-from-cwd
```

The two flags matter:

- **`--context claude-code`** trims away the tools Claude Code already has of
  its own, so the model isn't choosing between two file readers.
- **`--project-from-cwd`** activates the repo you launched from, no manual
  activation step.

(On my NixOS box Serena is installed as a package and the command is just
`serena start-mcp-server` with the same flags - the `uvx` form above works
anywhere.)

> 💡 Verify it took: ask Claude to "find every caller of X". If it answers
> with a reference list instead of a grep transcript, Serena is doing the
> work.

## 2. Official plugins - docs and language servers

The [official marketplace](https://github.com/anthropics/claude-plugins-official)
ships with Claude Code; `/plugin install <name>@claude-plugins-official`
installs from it. Four of mine come from there:

- **[context7](https://github.com/upstash/context7)** - fetches current
  library documentation before Claude writes code against a stale memory of
  an API. The single biggest fix for confidently-wrong framework code.
- **LSP plugins** - `typescript-lsp`, `pyright-lsp`, `gopls-lsp`,
  `jdtls-lsp`. Real compiler diagnostics for the languages you write, so
  Claude sees the red squiggles too.
- **skill-creator** - scaffolds, evaluates, and tunes your own skills.
- **claude-md-management** - audits and improves the `CLAUDE.md` files that
  steer every session.

```bash
# inside a Claude Code session
/plugin install context7@claude-plugins-official
/plugin install typescript-lsp@claude-plugins-official
/plugin install skill-creator@claude-plugins-official
/plugin install claude-md-management@claude-plugins-official
```

## 3. impeccable - design taste as a plugin

[impeccable](https://github.com/pbakaus/impeccable) is a marketplace of
frontend design skills: critique, layout, typography, animation, hardening.
When a UI needs to stop looking like generic AI output, these are the skills
that get invoked.

```bash
/plugin marketplace add pbakaus/impeccable
/plugin install impeccable@impeccable
```

## 4. Firecrawl - the open web

[Firecrawl](https://www.firecrawl.dev) turns the web into clean markdown:
search, scrape, crawl, extract. The
[MCP server](https://github.com/firecrawl/firecrawl-mcp-server) means Claude
can research a library, read a changelog, or pull a spec without you pasting
it in.

```bash
claude mcp add firecrawl --scope user \
  --env FIRECRAWL_API_KEY=fc-your-key -- \
  bunx firecrawl-mcp
```

## 5. Playwright - eyes on a real browser

[Playwright MCP](https://github.com/microsoft/playwright-mcp) gives Claude a
browser it can drive: navigate, click, evaluate, screenshot. For frontend
work this closes the loop - Claude restyles a page, then *looks at it* and
fixes what's off. The neumorphism pass on this very site was verified that
way.

```bash
claude mcp add playwright --scope user -- bunx @playwright/mcp@latest
```

On NixOS, point it at the system browser with
`--executable-path /run/current-system/sw/bin/google-chrome-stable`.

## 6. GitHub - the hosted MCP

GitHub runs the [official MCP server](https://github.com/github/github-mcp-server)
as a hosted endpoint, so there is nothing to install - one HTTP registration
and Claude reads issues, reviews PRs, and searches code across your account:

```bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer $GITHUB_PAT"
```

Use a fine-grained PAT scoped to the repos you actually want the agent
touching.

## 7. Secrets stay in 1Password

Two habits keep tokens out of dotfiles. First, the
[op CLI](https://developer.1password.com/docs/cli/) with a service account,
so `op read` works headless in any shell. Second, wrap an MCP server's launch
command so its token resolves at start and never lands on disk - this is how
my [monday.com MCP](https://github.com/mondaycom/mcp) runs:

```bash
claude mcp add-json monday --scope user '{
  "command": "sh",
  "args": ["-c", "exec monday-api-mcp -t \"$(op read op://YourVault/monday/credential)\""]
}'
```

The same wrapper pattern works for any server that takes a key as a flag or
an env var. Rotate the item in 1Password and every agent picks it up on the
next launch.

The full picture - scoped vaults, per-directory service-account tokens, and a
gitleaks pre-commit gate - is its own guide:
[Using AI agents safely with 1Password and devenv](/writing/using-ai-agents-safely-with-1password-and-devenv).

## 8. devenv - a pinned toolchain per directory

[devenv](https://devenv.sh) (source at
[cachix/devenv](https://github.com/cachix/devenv)) declares each project
tree's toolchain and environment in Nix, so every agent session gets the same
`bun`, `terraform`, and `go` as CI - no "works on my machine" drift between
you, the agent, and the pipeline:

```nix
{ pkgs, ... }:
{
  env.GH_CONFIG_DIR = "/home/wihan/.config/gh-vanillauys";
  packages = [ pkgs.bun pkgs.terraform pkgs.gitleaks pkgs.go ];
}
```

The `env` block is the sleeper feature for agents: per-process variables like
`GH_CONFIG_DIR` pin the tree to one GitHub identity, without mutating any
global state. Details in the
[safety guide](/writing/using-ai-agents-safely-with-1password-and-devenv).

## Verify the stack

```bash
claude mcp list        # ✅ every server shows "connected"
```

Then open a session in a real repo and watch the tools get used:

```text
> find every reference to repoLive        # Serena answers with symbols
> what changed in astro 7's view transitions?   # context7 / firecrawl fetch it
> screenshot the homepage in dark mode          # playwright opens the browser
```

If a server shows "failed", `claude mcp get <name>` prints the command it
tried - the problem is almost always a missing binary or an unresolved
secret.

## Further reading

- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
- [Serena's readme](https://github.com/oraios/serena) - the design notes
  explain *why* symbolic tools beat grep, and they're worth the read
- [Model Context Protocol](https://modelcontextprotocol.io) - the standard
  all of this speaks