Once Claude Code is installed and connected to an API, many people find it works but does not quite fit their project yet. Every new session starts with re-explaining how to run the tests and which directories are off limits, and connecting it to a database or a browser seems like a project of its own. Those two gaps map to two of Claude Code's advanced features: CLAUDE.md, which teaches it your project's rules, and MCP, which connects it to external tools. This guide covers where each one lives, how to write it, and the commands you need. If you have not installed Claude Code yet, start with the macOS and Linux setup guide or the Windows setup guide.
What CLAUDE.md Is
CLAUDE.md is Claude Code's project memory. It is read automatically at the start of every session, and it should contain what you would otherwise tell a new teammate before they touch the code. Done well, the model knows from the first message how to build, how to test and what your conventions are.
It can live in several places:
| Location | Scope | Good for |
|---|---|---|
| CLAUDE.md in the project root | This project; commit it to share with the team | Build commands, conventions, architecture notes |
| CLAUDE.md in a subdirectory | Read when working on files in that directory | Module-specific rules |
| ~/.claude/CLAUDE.md | Every project on your machine | Personal preferences such as answer language or commit message style |
In a monorepo, put shared conventions in the root file and add more specific CLAUDE.md files for the frontend and backend.
Generating a First Draft
Start Claude Code in your project and run:
/initIt analyzes the codebase and writes a draft covering build commands, layout and the main conventions. Always edit the result: remove anything obvious and add the pitfalls only you know about. Later, /memory opens the memory files for editing.
What to Include and What to Leave Out
Include what the model cannot infer from the code, or tends to get wrong:
- Commands: installing dependencies, running a single test, linting, starting the dev server
- Conventions: rules your tooling does not enforce, such as error-handling patterns, naming, libraries to avoid
- Architecture map: what each core directory owns and where a given kind of change belongs
- Workflow: checks that must pass before a commit, how database migrations are generated
- Known pitfalls: a test that needs a local service, a config file that is generated and must not be edited
Leave out generic advice ("write clean code"), facts that are obvious from the code, and long background stories. A compact example:
# Project conventions
## Commands
- Install: pnpm install
- Single test: pnpm test -- path/to/file.test.ts
- Before committing: pnpm lint && pnpm typecheck
## Rules
- The API layer throws AppError; never throw a bare Error
- Database access lives in src/repo/ only; no SQL in business logic
## Watch out
- src/generated/ is generated code; do not edit it by hand
- e2e tests need a local Redis; unit tests do notFor longer documentation, reference other files with @ instead of pasting everything — a line such as @docs/architecture.md lets it pull that file in when relevant.
Keep It Short: It Costs Tokens Every Turn
CLAUDE.md is sent with every request, so every extra line adds input tokens to every turn. A good target is one or two screens, pruned regularly. Prompt caching lowers the cost of the repeated part but does not make it free. The Claude Code token-saving guide has more ways to keep context lean.
What MCP Is
MCP (Model Context Protocol) is the standard way for Claude Code to call external tools. With MCP servers connected, the model can drive a browser, query a database, or read and update issue trackers and online docs — not just edit local files and run commands.
There are two kinds of MCP servers:
- Local servers run as child processes on your machine, usually started with npx or uvx
- Remote servers are reached over HTTP, hosted by the provider, and often require signing in
Adding MCP Servers
For a local server, put the launch command after --. For example, Playwright browser automation:
claude mcp add playwright -- npx @playwright/mcp@latestPass environment variables with -e:
claude mcp add my-db -e DATABASE_URL=postgres://localhost/dev -- npx -y your-db-mcp-serverFor a remote server, use --transport http, and --header when it needs an auth header:
claude mcp add --transport http my-api https://mcp.example.com/mcp \
--header "Authorization: Bearer your-token"Managing servers:
claude mcp list # list configured servers
claude mcp get playwright # show one server's configuration
claude mcp remove playwrightInside a session, /mcp shows each server's connection status, and it is also where you complete OAuth sign-in for remote servers that need it.
The Three Scopes
Choose a scope with --scope when adding a server:
| Scope | Stored in | Who can use it |
|---|---|---|
| local (default) | Your machine, for the current project | Only you, only in this project |
| project | .mcp.json in the project root | The whole team, once committed |
| user | Your user configuration | Only you, in every project |
Use the project scope for servers the whole team needs. The resulting .mcp.json looks like this:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}Because .mcp.json is committed, never put secrets in it. It supports environment variable references such as ${DATABASE_URL}, so each developer supplies real values in their own environment. For safety, Claude Code asks for your approval before using servers declared in a project's .mcp.json for the first time.
Using MCP Through Zivv
MCP servers run on your side. Claude Code sends the tool definitions along with each request, the model decides which tool to call, and Claude Code executes it locally. All of this uses the standard Anthropic tool-use protocol, so it works through Zivv with no extra configuration.
Two things to keep in mind:
- Tool definitions cost tokens: every connected server adds all of its tool definitions to every request. Remove servers you do not use, or add them with local scope only in the projects that need them
- Check tool support when switching models: every Claude model supports tool use. DeepSeek, GLM and other models that can drive Claude Code also support it, but Claude is usually more reliable at complex multi-tool work — see the DeepSeek, Qwen and GLM guide
A Word on Security
An MCP server can read data and take actions with the same permissions as any program on your machine. Install servers only from sources you trust, give database servers a read-only account or a test database, and review changes to a shared .mcp.json the way you review code.
FAQ
Q: Do I need to restart the session after editing CLAUDE.md? A: New sessions pick up the latest version. In a running session, you can simply ask the model to re-read CLAUDE.md.
Q: Which language should CLAUDE.md be written in? A: Whatever your team uses. What matters is that it is short, specific and actionable.
Q: An MCP server will not connect. What should I check? A: Run /mcp in the session to see the status and error, then run the server's launch command directly in a terminal to confirm its dependencies and environment variables.
Q: Are subagents the same thing as MCP? A: No. Subagents are Claude Code's way of handing a task to a separate context; MCP is the protocol for external tools. You can use both together.
Wrapping Up
CLAUDE.md removes the need to re-explain your project every session, and MCP takes Claude Code beyond local files. With both in place it behaves much more like a teammate who knows the codebase. Model calls still go through Zivv as usual: sign up for Zivv, set the two environment variables described on the Claude Code page, and start building on these features.