MCP Skills: Global vs Project Scope Across All Platforms
When to make an MCP skill available to all projects vs one project — decision framework, config paths for every platform, team collaboration workflow, and how to handle secrets safely.
🕐Last updated 4 March 2026
Global config = personal tools and credentials, available everywhere on your machine. Project config = team tools, committed to git, only active in that project. Never put actual API keys in project config — use ${ENV_VAR} references instead. Project config overrides global when names clash.
The question of "should this skill be global or project-scoped?" comes up every time you add something new. Get it wrong and you end up with personal credentials in a git repo (bad) or a useful tool missing from half your projects (annoying). Here's the framework we use.
The Decision Logic
Is this a personal tool I want everywhere? (weather, notes, search)
→ Global config
Does it use credentials that are mine, not the project's?
→ Global config (never commit personal secrets)
Should everyone on the team have this automatically?
→ Project config (commit to git)
Is this tool specific to this project's infrastructure?
→ Project config
Not sure?
→ Start global. Move to project when you share it.We accidentally committed a GitHub personal access token in a project config file once. GitHub's secret scanning caught it and invalidated the token within minutes — then sent an alert. Annoying but not catastrophic. The lesson: don't put any real credential in a committed file, even "just for testing". Use ${GITHUB_TOKEN} and set the value locally.
Config Locations: Every Platform
Claude Desktop
Global only — no project-level concept.
| OS | Config path |
|---|---|
| Mac | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%Claudeclaude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
Claude Code
| Scope | Mac/Linux | Windows |
|---|---|---|
| Global | ~/.claude/settings.json | %USERPROFILE%\.claude\settings.json |
| Project | .claude/settings.json | .claude\settings.json |
Cursor
| Scope | Mac/Linux | Windows |
|---|---|---|
| Global | ~/.cursor/mcp.json | %USERPROFILE%\.cursor\mcp.json |
| Project | .cursor/mcp.json | .cursor\mcp.json |
OpenClaw
# Global (default)
openclaw skills install weather
# Project-scoped
openclaw skills install weather --projectTeam Workflow: The Right Way
- Each developer sets up their own global config with personal tools
- Create a project config with team tools — no personal credentials
- Commit the project config to git
- Use
${VAR_NAME}references for anything that varies per developer - Document the required env vars in your README
Project config (safe to commit):
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@trustedskills/postgres-mcp"],
"env": { "DATABASE_URL": "${DATABASE_URL}" }
}
}
}Each developer's local .env (NOT committed):
DATABASE_URL=postgresql://localhost:5432/myapp_dev.env to your .gitignore before you create the file. It's much easier than trying to scrub it from history later.
Frequently Asked Questions
Can the same skill be in both global and project config?
Yes. Project config takes precedence. This lets you override a global skill with a project-specific version — useful when a project needs a different database connection than your personal setup.
How do I share MCP skills with my team?
Add the skill config to your project's config file and commit it to git. Every team member who clones the repo gets it automatically.
What's the safest way to handle API keys in project config?
Use ${VAR_NAME} references. Set actual values in each developer's local environment or a gitignored .env file. The committed config file contains zero secrets.
Does Claude Desktop support project-level config?
No — it's global only. For project-level skill management, use Claude Code or Cursor, which both support project config files.
TrustedSkills Team
The TrustedSkills team builds and tests AI agent integrations across Claude, OpenClaw, Cursor, and VS Code. We verify every skill in our registry and have set up hundreds of MCP configs across every major platform.