Claude Code gidas pradedantiesiems

The difference that matters

A chat assistant is a very good autocomplete that cannot see your project. Claude Code is the same model wired into your machine: it can list a directory, read a file, run npm test, and write changes to disk.

That is the whole appeal, and also the whole risk. Everything else in this guide is about the second half of that sentence.

01 · Install it

Pick one. The native installer keeps itself up to date in the background; the package managers do not.

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

Or through a package manager, if you would rather:

brew install --cask claude-code
            winget install Anthropic.ClaudeCode

Check it landed:

claude --version

That prints a version number followed by (Claude Code). Homebrew and WinGet installs do not auto-update — run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode yourself now and then.

02 · Log in

Start it once and it walks you through authentication in the browser:

claude

You can sign in with a Claude subscription (Pro, Max, Team or Enterprise), a Claude Console account with pre-paid credits, or an enterprise cloud provider. Credentials are stored, so this is a one-time step. To switch accounts later, type /login inside a running session.

03 · Your first session

Claude Code works inside a directory. Go to a project and start it there — that directory is what it can see.

cd /path/to/your/project
            claude

Do not start by asking it to build something. Start by asking it to explain something, because that tells you how much it actually understands:

what does this project do?
            where is the main entry point?
            explain the folder structure

You do not have to paste files in or add them to context by hand. It reads what it needs as it goes.

04 · Your first change

Now give it something to do:

add a hello world function to the main file

It finds the file, shows you the change, and depending on the permission mode either asks first or just does it.

05 · The commands worth memorising

Two kinds: shell commands that start a session, and slash commands you type inside one.

Type / on its own to see every command and skill available in this project.

06 · What it can reach

The working directory you launched it in, and what your user account can touch from a shell. That is a bigger surface than most people picture the first time.

Which is why the next three steps of this guide exist: telling it about your project so it stops guessing, and putting guardrails on so the things you never want touched stay untouched.

Getting unstuck

• Be specific. “Fix the login bug where users see a blank screen after wrong credentials” beats “fix the bug”.
• Let it look before it leaps — ask it to analyse the schema before asking it to change anything.
• Break big asks into numbered steps; it follows a list well.
• ↑ for history, Tab to complete a command, /help when lost.

Verified against the official Claude Code documentation, September 2026. Claude Code moves quickly, so check the official documentation before relying on a detail here.

The tell that you need one

You correct the same thing twice. You explain the folder layout again. You say “we use pnpm, not npm” for the third session running.

Every Claude Code session begins with a fresh context window. Nothing carries over on its own. CLAUDE.md is the file it reads at the start of every session, so anything in there is something you never have to type again.

01 · Let it write the first draft

Do not start from a blank file. Inside your project, run:

/init

It reads the codebase and writes a starting CLAUDE.md with the build commands, test commands and conventions it can find. If one already exists, /init suggests improvements instead of overwriting it.

Then refine by hand. The useful half is what it could not discover on its own: why things are the way they are, and the rules that differ from the tool defaults.

02 · Where the file goes

There are four places, and they all load — broadest first, so the most specific instruction is the last thing read.

Files in directories above your working directory load at launch too, root-down. Files in subdirectories load on demand, when Claude reads something in that folder. To see what actually loaded in this session, run /context and look under Memory files.

03 · What to write in it

Facts that should hold in every session: build and test commands, project layout, naming conventions, the “always do X” rules.

Specific beats tidy. Instructions you can verify get followed; vague ones get ignored.

• Keep it under about 200 lines. It loads into context every session, so a long file costs tokens and, counter-intuitively, gets followed less closely.
• Use headers and bullets. Claude scans structure the way you do.
• Remove contradictions. If two rules disagree, it may pick either one.
• Multi-step procedures do not belong here — those are skills.

04 · Splitting it up

Two mechanisms, for two different problems.

Imports pull another file in with @path. Good for organisation; it does not save context, because imported files load at launch as well.

See @README for the project overview and @package.json for the npm scripts.
            # Additional instructions
            - git workflow @docs/git-instructions.md

To mention a path without importing it, wrap it in backticks. @README imports; `@README` stays literal.

Path-scoped rules in .claude/rules/ only enter context when Claude touches a matching file, so they genuinely reduce noise:

---
            paths:
            - "src/api/**/*.ts"
            ---
            # API rules
            - Every endpoint validates its input
            - Use the standard error response shape

A rule with no paths field loads every session, same as .claude/CLAUDE.md. Personal rules that apply everywhere go in ~/.claude/rules/.

05 · The memory you don't write

Alongside the file you maintain, Claude keeps notes of its own. Auto memory is on by default, stored per repository on your machine.

It deliberately skips anything it could work out from the codebase, and anything your CLAUDE.md already says. Run /memory to browse, edit or delete what it saved — it is all plain markdown — and to toggle the feature off.

{
            "autoMemoryEnabled": false
            }

06 · When CLAUDE.md is the wrong tool

This is the part people learn the hard way. CLAUDE.md is context, not configuration. Claude reads it and tries to follow it. Nothing enforces it.

Same for anything that must run at a fixed moment — before every commit, after every edit. That is a lifecycle event, not a note.

Troubleshooting

• It is ignoring the file. Run /context first — if it is not listed under Memory files, it never loaded, and the problem is the location, not the wording.
• It is too big. Over ~200 lines adherence drops. Move sections into path-scoped rules so they load only when relevant.
• Instructions vanished after /compact. The project-root CLAUDE.md is re-read from disk after compaction. Anything you only said in conversation is not — which is the argument for writing it down.
• Rules contradict each other. Review the whole chain: user, project, nested, and .claude/rules/.

Verified against the official Claude Code documentation, September 2026. Claude Code moves quickly, so check the official documentation before relying on a detail here.

The problem

An agent that can run arbitrary shell commands will, sooner or later, try to run one you did not mean to approve. Guardrails catch that before it executes — not after.

What's inside

• A .claude/settings.json wiring up three hook registrations
• A guard.sh script implementing five distinct safety checks
• A plain-language explanation of what each check blocks and why
• Drop-in setup — one dependency (jq), no build step

How it's wired

Claude Code hooks are just shell commands the CLI runs before or after a tool call, fed a JSON payload on stdin. guard.sh reads that payload once and runs five checks against it. A PreToolUse hook can block the call outright (exit code 2); a PostToolUse hook can only observe, so it's used here for the audit log.

{
            "hooks": {
            "PreToolUse": [
            {
            "matcher": "Bash",
            "hooks": [
            { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/guard.sh" }
            ]
            },
            {
            "matcher": "Write|Edit|MultiEdit",
            "hooks": [
            { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/guard.sh" }
            ]
            }
            ],
            "PostToolUse": [
            {
            "matcher": "Bash|Write|Edit|MultiEdit",
            "hooks": [
            { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/guard.sh" }
            ]
            }
            ]
            }
            }

Three hook registrations, five checks — guard.sh looks at hook_event_name and tool_name to decide which checks apply to this call.

Try it yourself

This runs the exact same logic as guard.sh below, ported line for line — not a simplified demo. Type a command (or click an example), and see what the hook would actually do with it.

The five checks, one at a time

The full guard.sh script

#!/usr/bin/env bash
            # Claude Code Guardrails — guard.sh
            # Reads a PreToolUse/PostToolUse hook payload from stdin and decides
            # whether to allow, block, or just log the tool call.
            #
            # Exit codes (per Claude Code's hook contract):
            #   0 = allow (stdout/stderr shown to the user only)
            #   2 = block (stderr is fed back to Claude as the reason)
            #
            # This is a guardrail against mistakes, not a security boundary.
            # See the "What this does not protect against" section of the guide.
            # Deliberately no -e: a failed log write must never take the hook down,
            # because a hook that crashes is a hook that stops protecting you.
            set -uo pipefail
            payload="$(cat)"
            # One jq call instead of four, NUL-separated. Not @tsv + IFS=$'\t':
            # bash treats tab as IFS *whitespace*, so an empty field (e.g. no
            # .command on a Write call) collapses and every later field shifts left.
            # NUL can't appear inside a value, and `read -d ''` keeps empty fields
            # and multi-line commands intact.
            {
            read -r -d '' hook_event
            read -r -d '' tool_name
            read -r -d '' command
            read -r -d '' file_path
            } < <(printf '%s' "$payload" | jq -j '
            (.hook_event_name // ""), "\u0000",
            (.tool_name // ""), "\u0000",
            (.tool_input.command // ""), "\u0000",
            (.tool_input.file_path // ""), "\u0000"
            ')
            log_dir="$(dirname "$0")"
            log_file="$log_dir/guard.log"
            # $1 = outcome label (RAN / BLOCKED)
            write_audit_log() {
            printf '%s\t%s\t%s\t%s\n' \
            "$(date -Iseconds)" "$1" "$tool_name" "${command:-$file_path}" \
            >>"$log_file" 2>/dev/null || true
            }
            # Log the block BEFORE exiting. PreToolUse exit 2 stops the tool, so
            # PostToolUse never fires — without this line the blocked commands, the
            # ones you actually want a record of, would never reach the log.
            block() {
            write_audit_log "BLOCKED"
            echo "Guardrails blocked this: $1" >&2
            exit 2
            }
            # --- 1: destructive filesystem commands ----------------------------------
            # Flag-order independent: -rf, -fr, -r -f, --recursive --force all count.
            check_destructive_fs() {
            local c=" $command "
            if printf '%s' "$c" | grep -qE '(^|[;&|(]|[[:space:]])rm([[:space:]]|$)'; then
            local rec=0 force=0
            printf '%s' "$c" | grep -qE '([[:space:]]-[a-zA-Z]*[rR][a-zA-Z]*([[:space:]]|$)|[[:space:]]--recursive([[:space:]]|$))' && rec=1
            printf '%s' "$c" | grep -qE '([[:space:]]-[a-zA-Z]*f[a-zA-Z]*([[:space:]]|$)|[[:space:]]--force([[:space:]]|$))' && force=1
            if [ "$rec" -eq 1 ] && [ "$force" -eq 1 ]; then
            if printf '%s' "$c" | grep -qE '([[:space:]]/([[:space:]]|$)|[[:space:]]/\*|[[:space:]]~|\$HOME|[[:space:]]\./?([[:space:]]|$)|[[:space:]]\.\./?([[:space:]]|$)|--no-preserve-root)'; then
            block "recursive force-delete aimed at root, home, or the working directory."
            fi
            fi
            fi
            if printf '%s' "$c" | grep -qE 'dd[[:space:]].*of=/dev/'; then
            block "raw disk write via dd — this can destroy a whole disk."
            fi
            case "$command" in
            *":(){ :|:& };:"*) block "fork bomb pattern detected." ;;
            esac
            }
            # --- 2: force-push / history rewrite on protected branches ---------------
            check_protected_branch() {
            case "$command" in
            *"filter-branch"*)
            block "history-rewriting operation (filter-branch)." ;;
            esac
            # Only inspect what comes AFTER "push", so `cd main && git push origin dev`
            # is not mistaken for a push to main.
            local after_push
            after_push="$(printf '%s' "$command" | sed -n 's/.*[Pp]ush//p')"
            [ -z "$after_push" ] && return 0
            # A leading + in a refspec is a force push even without --force.
            if printf '%s' "$after_push" | grep -qE '(^|[[:space:]])\+[^[:space:]]*(main|master)([[:space:]]|:|$)'; then
            block "force-push to main/master via a + refspec."
            fi
            local forced=0
            printf '%s' "$after_push" | grep -qE '([[:space:]]-f([[:space:]]|$)|--force([[:space:]]|$)|--force-with-lease)' && forced=1
            [ "$forced" -eq 0 ] && return 0
            if printf '%s' "$after_push" | grep -qE '(^|[[:space:]]|:)(main|master)([[:space:]]|:|$)'; then
            block "force-push to main/master."
            fi
            if printf '%s' "$after_push" | grep -qE '[[:space:]]--all([[:space:]]|$)'; then
            block "force-push --all rewrites every branch, main/master included."
            fi
            }
            # --- 3: skipping safety checks -------------------------------------------
            check_skip_safety() {
            case "$command" in
            *"--no-verify"*|*"--no-gpg-sign"*)
            block "a flag that skips commit hooks or signature verification." ;;
            esac
            if printf '%s' "$command" | grep -qE 'chmod[[:space:]]+(-[a-zA-Z]+[[:space:]]+)*777'; then
            block "chmod 777 — overly permissive file permissions."
            fi
            # Any remote fetch piped into any shell: curl|sh, curl|bash,
            # wget|sh, wget | sudo bash, ...
            if printf '%s' "$command" | grep -qE '(curl|wget)[^|]*\|[[:space:]]*(sudo[[:space:]]+)*(ba|z|k|da|c)?sh([[:space:]]|$)'; then
            block "piping a remote script straight into a shell — read it first."
            fi
            }
            # --- 4: secrets ----------------------------------------------------------
            is_sensitive_path() {
            case "$1" in
            *".env"*|*"id_rsa"*|*"id_ed25519"*|*".aws/credentials"*|*".ssh/"*|*"credentials.json"*) return 0 ;;
            *".git/config") return 0 ;;
            esac
            return 1
            }
            # Write/Edit/MultiEdit tools
            check_sensitive_write() {
            if is_sensitive_path "$file_path"; then
            block "write to a sensitive/credentials path ($file_path). Edit it by hand instead."
            fi
            }
            # The same files, but written from the shell — `echo ... >> .env`, `tee`.
            # The file_path check above only sees the Write/Edit tools.
            check_secret_write_via_bash() {
            if printf '%s' "$command" | grep -qE '(>>?|tee[[:space:]]+(-a[[:space:]]+)*)[[:space:]]*[^[:space:]]*(\.env|id_rsa|id_ed25519|\.aws/credentials|credentials\.json|\.ssh/)'; then
            block "writing to a secrets file from the shell. Edit it by hand instead."
            fi
            }
            # --- dispatch ------------------------------------------------------------
            case "$hook_event" in
            PreToolUse)
            if [ "$tool_name" = "Bash" ]; then
            check_destructive_fs
            check_protected_branch
            check_skip_safety
            check_secret_write_via_bash
            fi
            case "$tool_name" in
            Write|Edit|MultiEdit) check_sensitive_write ;;
            esac
            ;;
            PostToolUse)
            write_audit_log "RAN"
            ;;
            esac
            exit 0

Requires jq (already on most dev machines; brew install jq / apt install jq if not). Make it executable once: chmod +x .claude/guard.sh.

What this does not protect against

This is a guardrail against mistakes — yours and the agent's — not a security boundary. It is pattern matching on a command string, and pattern matching can always be walked around. Being straight about that is the point:

• Deliberate evasion. Anything that hides the command from the matcher gets through: base64-decoding into a shell, writing a script and running it, an unusual alias, a language runtime shelling out.
• Prompt injection. If a page or file talks the agent into something destructive, these checks only catch it when the final command happens to match a pattern.
• Files pulled in with @. Attaching a file in the prompt doesn't call a tool, so PreToolUse never runs. The .env rule here does not stop .env being read that way — use a Read deny rule in permissions for that.
• Everything not on the list. There is no sudo rule, no network rule, no package-install rule. Five checks, that's it.
• Non-bash environments. It's a bash script with a jq dependency — on Windows it needs WSL or Git Bash.

Where it does earn its keep: the 2 a.m. rm -rf, the force-push to main you meant to aim at your branch, the curl | sh you didn't read, and a log of what actually happened.

Check that it's actually running

A hook that silently isn't wired up feels exactly like a hook that's working. Feed the script a payload by hand — no Claude Code required:

echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
            | .claude/guard.sh; echo "exit=$?"
            # expected:
            # Guardrails blocked this: recursive force-delete aimed at root, home, ...
            # exit=2

Then check registration with /hooks inside Claude Code, and run it with claude --debug to watch hooks fire. exit=0 where you expected 2 means the pattern didn't match; no output at all usually means the file isn't executable (chmod +x) or the path in settings.json is wrong.

Need to get past it on purpose? That's a fair question, and there's no clever answer: comment out the check, or move the hook into .claude/settings.local.json (git-ignored, yours only) instead of .claude/settings.json (committed, shared with the team). A guardrail you can't turn off is one people delete entirely.

Get it

These are the actual files, not a copy — the code blocks on this page are generated from them, so what you read above is byte-for-byte what you download.

That is the entire concept. Everything below is detail on how each box works.

01 · The moment you need them

You ask Claude to fix a login bug. It reads the code, forms a theory, and decides the fastest fix is to change a value in .env. That is a reasonable engineering instinct. It is also the one file you never want an agent to touch, because it holds production credentials and it is not in version control, so a bad edit is not recoverable with git checkout.

You could write “never edit .env” in CLAUDE.md. That usually works. But it is an instruction competing with every other instruction in context, and it is advisory: nothing enforces it.

02 · The analogy that makes it click

Think of Claude as a competent new employee in your office building, and hooks as the building's security system.

From there the three hooks you will use most explain themselves:

• PreToolUse is the badge reader outside the room. It checks before you go in, and it can refuse.
• PostToolUse is the quality inspector who walks in afterwards. It cannot un-open the door, but it can tidy up, log what happened, or flag a problem.
• Stop is the person at the exit asking “did you actually run the tests?” before you go home — and who can send you back in.

03 · Where hooks sit in a run

A Claude Code session is a loop, and hook events are named points along it. Here is the path a single tool call takes:

Scroll the row sideways if it is cut off. The important shape: PreToolUse is the only point that can stop an action before it happens. Everything after it is reacting to something that already ran.

05 · Your first hook: format on every edit

The smallest useful hook does not block anything. It runs Prettier over whatever file Claude just wrote, so formatting stops being something either of you thinks about.

{
            "hooks": {
            "PostToolUse": [
            {
            "matcher": "Edit|Write",
            "hooks": [
            {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --write"
            }
            ]
            }
            ]
            }
            }

The command reads the same JSON payload on stdin, pulls one field out of it with jq, and passes it to Prettier.

06 · The one that says no

Now the .env problem from the top. This is a real hook, not pseudocode: it reads the payload on stdin, compares the target path against a protected list, and answers.

#!/usr/bin/env node
            import { readFileSync } from "node:fs";
            import path from "node:path";
            const PROTECTED = [
            /(^|\/)\.env(\..+)?$/,   // .env, .env.local, .env.production
            /(^|\/)\.git\//,         // anything inside .git
            /(^|\/)\.ssh\//,         // keys
            /(^|\/)credentials\.json$/,
            ];
            // Claude Code writes the call description to stdin as JSON.
            const payload = JSON.parse(readFileSync(0, "utf8"));
            const target = payload.tool_input?.file_path ?? "";
            const rel = path.relative(payload.cwd ?? process.cwd(), target) || target;
            if (PROTECTED.some((re) => re.test(rel))) {
            process.stdout.write(JSON.stringify({
            hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "deny",
            permissionDecisionReason:
            `${rel} is protected. Change it by hand, or ask a human.`,
            },
            }));
            }
            // Print nothing = no opinion. The normal permission flow continues.
            process.exit(0);

Two things worth noticing. It says why, not just no — that reason goes back to Claude, which is the difference between it getting stuck and it finding another route. And silence is a valid answer: a hook that has no opinion should print nothing rather than approving everything.

Run something through it

Pick what Claude tries to do and watch the hook decide. The rules below are the ones in the script above.

07 · Hooks are not only about blocking

Blocking is the loudest use, not the most common one. Six things people actually wire up:

The Enrich row is worth a second look: on a few events — SessionStart, UserPromptSubmit among them — whatever your script prints on stdout is added to the context Claude can see. A three-line shell script can tell it which branch you are on.

08 · Rules versus judgement

A hook does not have to be a script. Alongside command, a hook can be a prompt or an agent — Claude evaluating the situation instead of your regex.

09 · What it looks like assembled

Put four small hooks together and the loop stops being a chat and starts being a workflow with checks in it:

None of those four is clever on its own. Together they mean the agent cannot touch your secrets, cannot leave the codebase badly formatted, cannot quietly finish on a broken build, and cannot claim it did not know which branch it was on. That is the whole pitch: same model, bounded system.

10 · A hook is code. Treat it like code.

A command hook runs as a shell command with your permissions. Not Claude's permissions, not a sandbox — yours. It can modify or delete anything your user account can reach, and it runs automatically, without asking, on every matching call.

• Validate the input. The payload describes something the agent proposed; treat the strings in it as untrusted.
• Quote your variables. An unquoted $VAR in a shell hook is a command-injection hole, and the value came from a model.
• Guard against path traversal. Resolve to an absolute path before comparing, so ../../.env does not sail past a check that only looked at the basename.
• Use absolute paths for the script itself, so behaviour does not depend on the working directory.
• Do not read secrets in a hook just because it is convenient.

Hook event reference

The ones worth knowing by name, and what each is for.

Behaviour and event names verified against the official Claude Code hooks reference, September 2026. Hooks are evolving quickly — check the official reference before relying on a detail here.

The moment to write one

The cost of a skill is about five minutes. The cost of not writing it is retyping a paragraph forever, slightly differently each time, and getting slightly different results because of it.

01 · Where they live

A skill is a folder with a SKILL.md inside. The folder name becomes the command name.

Legacy command files namespace by subdirectory: .claude/commands/frontend/component.md becomes /frontend:component.

02 · What a SKILL.md looks like

YAML frontmatter, then plain markdown instructions. That is the whole format.

---
            name: review
            description: Review the current diff for bugs before I open a PR
            argument-hint: [branch]
            ---
            ## Review the diff against $ARGUMENTS
            1. Read the full diff, not just the changed lines
            2. Flag anything that would fail CI
            3. Check the tests actually cover the new branch of logic
            4. Report findings worst-first, and stop

The fields worth knowing:

03 · Arguments

Everything typed after the command lands in $ARGUMENTS:

Summarise these changes: $ARGUMENTS

/summarise add search to the header → Claude sees the whole sentence.

For more than one, use positions:

---
            arguments: [component, fromLang, toLang]
            ---
            Migrate the $component component from $fromLang to $toLang.
            Preserve behaviour and tests.

/migrate Button JavaScript TypeScript.

04 · The part that makes skills actually useful

A skill does not have to be static text. It can run commands and paste the real output into the prompt before Claude ever reads it.

## Current state
            !`git status --short`
            !`git diff --stat`
            ## Instructions
            Review only the files listed above.

And it can pull whole files in with @:

## Conventions to follow
            @./.eslintrc.json
            ## Code under review
            @./src/main.js

05 · Pre-approving the tools it needs

A skill that stops four times to ask permission is not saving you anything. allowed-tools grants exactly what this command needs, for this turn only:

---
            name: commit
            description: Stage and commit the current changes
            disable-model-invocation: true
            allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
            ---
            Stage the changes, write a message describing why rather than what,
            and commit. Do not push.

Note disable-model-invocation: true. Anything that writes, deploys or publishes should be something you trigger deliberately, not something the model can decide to run.

06 · A full one, end to end

---
            name: fix-issue
            description: Fix a GitHub issue by number. Use when asked to fix an issue.
            argument-hint: [issue-number]
            arguments: [issue]
            allowed-tools: Bash(gh issue view *)
            disable-model-invocation: true
            ---
            ## Fix issue #$issue
            ### The issue
            !`gh issue view $issue --json title,body,comments`
            ### Steps
            1. Understand what is actually being reported above
            2. Find the relevant files yourself
            3. Implement the fix in the smallest change that works
            4. Run `npm test`
            5. Commit as `fix(#$issue): <what changed>`

Run /fix-issue 123 and Claude starts with the real issue text already in front of it, rather than asking you to paste it.

Rules of thumb

• Write the description for Claude, not for yourself — it is what decides whether the skill gets picked up automatically.
• Keep SKILL.md short. It loads when invoked, so a long one costs context every time.
• Ground it in live data with ! instead of describing the state in prose.
• Anything destructive gets disable-model-invocation: true.

Verified against the official Claude Code documentation, September 2026. Claude Code moves quickly, so check the official documentation before relying on a detail here.

The signal that you need it

You keep copying things into the chat. A stack trace out of Sentry. A ticket out of Jira. A row out of the database. Every paste is context you had to fetch by hand, and it is stale the moment you paste it.

MCP (Model Context Protocol) is an open standard for connecting an agent to external tools and data. Claude Code speaks it, so anything with an MCP server — and most of the tools you already use have one — becomes something Claude can read and act on directly.

01 · Three kinds of server

02 · Adding one

A local server runs a command. Everything after -- is passed to that command untouched:

claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
            -- npx -y airtable-mcp-server

A remote one just takes a URL:

claude mcp add --transport http notion https://mcp.notion.com/mcp

With a token, if the service uses one rather than OAuth:

claude mcp add --transport http secure-api https://api.example.com/mcp \
            --header "Authorization: Bearer your-token"

03 · Scope: who gets this server

The flag that decides whether this is yours, this project's, or the team's.

claude mcp add --transport http shared-server --scope project https://example.com/mcp

04 · The committed file

Project-scoped servers land in .mcp.json at the repo root, so a teammate who clones the project gets the same tooling:

{
            "mcpServers": {
            "notion": {
            "type": "http",
            "url": "https://mcp.notion.com/mcp"
            },
            "database-tools": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@example/mcp-server"],
            "env": {
            "DB_URL": "postgresql://localhost/mydb"
            }
            }
            }
            }

05 · Logging in

Most hosted servers use OAuth. Add the server, then authenticate from inside a session:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

That opens the browser login flow. From the shell, claude mcp login sentry does the same, and claude mcp logout sentry clears the credentials again.

06 · How the tools show up

Once connected, the server's tools appear under a predictable name:

mcp__<server-name>__<tool-name>
            # a `query` tool from a server named `database`
            mcp__database__query

Which matters, because that name is what you write in permission rules, in a skill's allowed-tools, in a subagent's tool list, and in hook matchers. A matcher of mcp__database__.* catches everything that server exposes.

So the guardrails you already know apply here unchanged: an MCP tool is just another tool call, and a PreToolUse hook can deny it like any other.

07 · Managing them

claude mcp list              # everything configured
            claude mcp get notion        # details for one
            claude mcp remove notion     # disconnect it
            claude mcp add-from-claude-desktop   # import what you already set up

/mcp inside a session shows live connection status, which is the first thing to check when a tool silently is not there.

08 · The part to be careful about

An MCP server decides what content enters Claude's context. That makes a server you do not control a genuine attack surface, not a theoretical one.

• Trust the server before you connect it. A server that fetches external content can feed instructions into your session — this is prompt injection, and the agent has your permissions.
• Project-scoped servers ask for approval before first use, because they arrive in a file someone else can commit.
• headersHelper runs a shell command on your machine to produce auth headers. Read it before you approve it.
• Scope narrowly. A read-only database server is a very different risk from one that can write.

Verified against the official Claude Code documentation, September 2026. Claude Code moves quickly, so check the official documentation before relying on a detail here.