Set up an MCP filesystem server for one project

An agent that can inspect and edit files can help with routine project work. It can also change the wrong file if you give it a broad target. An MCP filesystem server provides a way to connect file tools to an agent; the important setup decision is which directory the server may reach.

This walkthrough uses the commonly used @modelcontextprotocol/server-filesystem package as an example. MCP clients differ in how they store server settings, so check your client’s current instructions before adding the entry.

1. Choose a workspace

Start with a project directory you can afford to test on. If the repository contains secrets, production credentials, or unrelated projects, make a separate working copy and remove anything the agent does not need. A small scope is easier to review than an entire home directory.

Find the directory’s absolute path. Use the full path rather than relying on a shortcut such as a tilde, because clients do not all expand paths the same way. For example, use /Users/alex/work/demo on macOS or /home/alex/work/demo on Linux, replacing the example with your own path.

2. Add the server to your MCP client

For a client that launches local servers over standard input and output, a typical configuration entry names the server filesystem, sets its command to npx, and supplies these arguments in order: -y, @modelcontextprotocol/server-filesystem, and the absolute path to your project. The last argument is the directory boundary. Do not substitute your home directory or a disk root just to make more files available.

Place that entry in the MCP server section of your client’s configuration, following the client’s required JSON structure and file location. The example assumes Node.js and npm are available to run npx. If your client uses a different launch method, follow its documented format while keeping the same narrow directory scope.

Save the configuration and restart or reconnect the client if its instructions require it. Check the client’s server status or logs for startup errors. A misspelled path, invalid JSON, or missing runtime can prevent the server from launching; do not respond to a startup failure by widening the allowed path.

3. Verify the boundary before editing

Ask the agent to list files in the test project, then read a harmless file. Confirm that the results match what you expect. Next, ask it to read a file outside the configured directory. It should not be able to access that path through the filesystem server. If it can, stop and inspect the actual server arguments and client configuration before using the connection.

Test a write with a disposable file. Have the agent make one small change, then inspect the diff yourself. This checks both that the server can write where expected and that you can review what changed. Keep the first test away from source files that are difficult to restore.

4. Treat the allowlist as one control

The configured directory limits the filesystem tools’ intended reach, but it is not a complete operating-system sandbox. The server runs as a local process under the permissions of the account that launched it. Keep the project free of unnecessary secrets, use a dedicated workspace when the work is sensitive, and avoid giving the process access to directories it does not need.

Also separate permission from instruction. Tell the agent which files it should edit and what it must leave alone, but do not treat a prompt as an access-control mechanism. The server’s directory scope sets a boundary for its file tools; your review catches mistakes within that boundary. For operations where a mistaken action needs a person’s approval, see how to put human approval in front of risky MCP tools.

5. Expand only after a successful test

If the agent needs a second directory, add only that directory using the syntax supported by the server and client, then repeat the read and out-of-scope tests. Do not assume that a path visible to your terminal is automatically exposed to the agent, or that every client handles server configuration in the same way. Keep a note of the exact paths you allowed so the setup can be checked later.

A local filesystem server and a network-accessible MCP server have different exposure boundaries. If the task changes to hosting an MCP server on a web domain, this guide to deploying agent discovery files and an MCP server on a web domain addresses that separate setup; a local launch configuration is not a remote deployment plan.

ZES publishes guides and tutorials on MCP and agent development, including an MCP Starter Kit with five ready-to-deploy servers listed for $9. Whatever starting point you use, keep the first filesystem connection limited to a test project, verify its boundary, and review every edit before applying it to important work.