Fundamentals

Global or project: where your AI tool looks for its config

Every AI tool asks you the same question when you install something into it, and most of them ask it in different words: just you or the whole team, this project or all of them. Get it wrong and you either install the same thing five times or turn something on everywhere and forget it is running.

Ali RizwanPublished 2 Oct 2026 · Updated 2 Oct 2026

5 min read2 views0 comments

Guide beginner

Add as preferred source on Google

You add an MCP server on Monday. On Wednesday you open a different project and it is gone. Or the opposite: you turn something on once, forget about it, and six weeks later it is still loading into every session you start, costing you context in projects that have nothing to do with it. Both are the same mistake, and it is not really a mistake. Nobody told you the question was being asked.

The question is always the same two

Every tool, every time, is asking you two things at once. Whose machine is this for? Just you, or anyone who works on this repo. Which projects does it apply to? This one, or all of them. That is it. The answers live in different files, and the files are the whole subject.

Three places, and what belongs in each

1. Your home folder — ~/.claude, ~/.codex, ~/.cursor and friends. Your settings, your sign-ins, your personal preferences. Nobody else ever sees this, and it applies to every project you open. 2. The project, committed — .mcp.json, AGENTS.md, .cursor/mcp.json. Checked into git, so everyone who clones the repo gets it. This is where anything the project genuinely needs belongs. 3. The project, not committed — CLAUDE.local.md and anything you have gitignored. Yours, for this repo only. Useful for a sandbox URL or test credentials you do not want in the repo.

What it looks like for an MCP server

Here is the same server, Playwright, added to each tool. Watch the scope line under each command — that is the fork, in each tool's own words.

Install it in

bash

claude mcp add playwright -- npx @playwright/mcp@latest

What you should see

A line confirming the server was added. Restart Claude Code, then check its MCP list for playwright.

Put it in .mcp.json in the project, committed so everyone who clones the repo gets it, or ~/.claude.json for every project on your machine, just you.

Claude Desktop has no add command — you write the config yourself.

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

What you should see

playwright appears in Claude Desktop's MCP list once it connects.

Put it in ~/Library/Application Support/Claude/claude_desktop_config.json for every project on your machine, just you.

bash

codex mcp add playwright -- npx @playwright/mcp@latest

What you should see

A line confirming the server was added. Restart Codex, then check its MCP list for playwright.

Put it in .codex/config.toml in the project, committed so everyone who clones the repo gets it, or ~/.codex/config.toml for every project on your machine, just you.

Cursor has no add command — you write the config yourself.

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

What you should see

playwright appears in Cursor's MCP list once it connects.

Put it in .cursor/mcp.json in the project, committed so everyone who clones the repo gets it, or ~/.cursor/mcp.json for every project on your machine, just you.

bash

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

What you should see

A line confirming the server was added. Restart VS Code, then check its MCP list for playwright.

Put it in .vscode/mcp.json in the project, committed so everyone who clones the repo gets it.

Antigravity has no add command — you write the config yourself.

json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

What you should see

playwright appears in Antigravity's MCP list once it connects.

Put it in .agents/mcp_config.json in the project, committed so everyone who clones the repo gets it, or ~/.gemini/config/mcp_config.json for every project on your machine, just you.

bash

gemini mcp add playwright npx @playwright/mcp@latest

What you should see

A line confirming the server was added. Restart Gemini CLI, then check its MCP list for playwright.

Put it in .gemini/settings.json in the project, committed so everyone who clones the repo gets it, or ~/.gemini/settings.json for every project on your machine, just you.

opencode has no add command — you write the config yourself.

json

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest"
      ]
    }
  }
}

What you should see

playwright appears in opencode's MCP list once it connects.

Put it in opencode.json in the project, committed so everyone who clones the repo gets it, or ~/.config/opencode/opencode.json for every project on your machine, just you.

Four of those take a command that writes the file for you. The rest you write yourself. Either way you are choosing between the same two files.

What it looks like for a CLI

A terminal agent keeps two things: its own settings, which are yours, and the instructions it reads about your project, which are the team's. The second one is where these tools disagree most.

Look it up for

Command: claude Settings and sign-in: ~/.claude/ Instructions for this project: CLAUDE.md Instructions for every project, yours only: ~/.claude/CLAUDE.md AGENTS.md: Reads it only where there is no CLAUDE.md.

Claude Code docs(opens in a new tab)

How to decide, in one line each

Does the project need it to work? Commit it. A new teammate cloning the repo should get a working setup, not a list of things to install. Is it a preference, a key, or a habit? Home folder. Your editor layout is not the project's business. Is it both? Commit the config, keep the credential out of it. Not sure? Start project-scoped. A thing that is on in one repo is easy to find later. A thing that is on everywhere is invisible until it causes a problem.

The cost of global, which nobody mentions

Anything installed globally loads in every session, in every project, forever. That is the point of it, and it is also the bill. Every MCP server you add globally puts its tool definitions into the context window of every conversation you start, including the ones about a completely unrelated codebase. A few of those and you have spent real context before typing anything. People notice the model getting vaguer and blame the model. And a global install is a thing you stop seeing. Six servers you added over three months, all connected, most of them irrelevant to what you are doing today.

Check what you have actually got

Worth doing now rather than when something breaks.

Paste this into your AI tool

List every MCP server, skill and instruction file you can currently see, and for each one tell me whether it is coming from this project or from my home folder. Do not change anything.

Open it in your AI tool. Clicking copies the prompt, and ChatGPT and Grok open with it already filled in.

More tools

App builders, in your browser:

Code editors on your computer. Open app only works once it is installed, so use Get it first if you do not have it.

CursorOpen app Get it(opens in a new tab)
VS CodeOpen app Get it(opens in a new tab)
Antigravity IDEOpen app Get it(opens in a new tab)
Antigravity 2.0Open app Get it(opens in a new tab)

Want the full list? Browse all app builders and coding editors (IDEs).

The third one is worth running even if you are confident. It is the fastest way to find out that the file you have been carefully maintaining is not the one being read.

Comments

Nothing here yet. If something in this piece worked, or did not, say so.