Claude Code can connect to MCP servers, and the right configuration scope depends on who should use one: local for a single project, user for your projects, or project for a team configuration that requires approval in interactive sessions. MCP, the Model Context Protocol, connects Claude Code to external tools and data sources. Anthropic’s documentation spells out where each scope is stored and how to register and check a server.
Choose a configuration scope
Claude Code stores local and user MCP settings in ~/.claude.json, while project settings live in .mcp.json at the project root. The difference is how broadly each configuration applies and whether it can be shared:
| Scope | Applies to | Configuration location | Approval or sharing behavior |
| Local | The current project, for you | ~/.claude.json | Private to you and associated with that project path |
| User | All of your projects | ~/.claude.json | Applies across your projects; not shared with your team |
| Project | The current project | .mcp.json in the project root | Can be shared through version control; Claude Code prompts for approval in interactive sessions before using the server |
Choose local for a personal setup tied to one project. Choose user when you want the server available across your own projects. A project-scoped configuration is the team-oriented option, but sharing the file does not skip the interactive approval prompt.
Add an MCP server and check the connection
For a local server that uses stdio—a process running on your machine and communicating through standard input and output—the documented command pattern is:
claude mcp add [options] <name> -- <command> [args...]
The -- separates Claude Code’s options from the server command and its arguments; everything after it is passed to the server. The server’s executable and arguments depend on that particular app, so use its instructions for those values. A Craft-app test account published by pasqualepillitteri.it used this pattern for PhotoCraft with separate read and write roots, but its exact flags are specific to that example. Claude Code’s reference also documents claude mcp list to see configured servers and /mcp to inspect MCP status in a session.
claude mcp list
After adding a server, check its status rather than treating a successful configuration command as proof that it connected. Use /mcp in a Claude Code session to inspect the connection.
Check the work, not just the command result
An MCP server can complete an operation while the resulting document still needs a look. In task examples reported by pasqualepillitteri.it, a DeckCraft chart overlapped a slide title, and a WordCraft letter initially ran to two pages. Those observations are specific to the reported tasks; they are useful reminders to inspect the exported slide or document before relying on it. The account’s Craft test report also describes app-specific differences in commands and output, so don’t assume one Craft app’s setup flags fit another.
Folder limits have a boundary, too. PhotoCraft’s documentation says configured read and write roots restrict that server’s filesystem access. They do not set the permissions for every other Claude Code tool. In a FilmCraft task, the same pasqualepillitteri.it account reports that a shell-capable Claude Code tool saved a rendered frame after FilmCraft could not save it to the requested path. Treat server-level file roots and Claude Code’s other tools as separate permission surfaces. PhotoCraft’s MCP documentation and Claude Code’s MCP guide describe their respective boundaries and server-trust guidance.
Recover from a failed PhotoCraft batch
PhotoCraft’s command_batch runs steps in order, but it is not an all-or-nothing transaction: if a later step fails, earlier successful steps remain applied. PhotoCraft’s documentation recommends inspecting the document and its history after a failure, and experimenting on a duplicate or a new document.
- Pause before retrying. A retry can repeat work that already succeeded.
- Inspect the document and its history. Identify which batch steps took effect before deciding what to run next.
- Check files written to disk separately. Undoing document edits does not remove files the batch already wrote.
- Experiment on a duplicate or a new document. That gives you a separate working copy for testing operations.
These recovery details are specific to PhotoCraft. Its MCP documentation describes the batch behavior, the inspection steps, and the distinction between document undo and files already written to disk.
