This server provides secure, sandboxed file management for AI models. You can:
List allowed directories, browse directory contents, and create folders.
Read, write, append, move/rename, and delete files and directories, with automatic parent directory creation.
Search for files using glob patterns, and get file metadata.
Generate a comprehensive knowledge document (Markdown or PlantUML) from all stored files for quick context.
Optionally, use a password-protected web interface to browse the file store.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-chatgpt-file-store Save the summary of our conversation to notes/summary.md"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that lets ChatGPT (or any MCP client) save and manage files inside a sandboxed local folder on your Mac.
Everything ChatGPT does is confined to an allowed directory — it cannot read or write anywhere else on your machine.
ChatGPT gets these tools:
Tool | Purpose |
| Shows where ChatGPT is allowed to save/read |
| Lists files and folders in the store |
| Reads a text file |
| File metadata (size, modified time) |
| Finds files matching a pattern ( |
| Returns the whole store as one body of knowledge — Markdown, or PlantUML when it describes a flow |
| Saves a file (creates folders automatically) |
| Appends to a running log/notes file |
| Creates folders |
| Moves/renames files |
| Deletes a file or folder |
Related MCP server: Local Files MCP Server
Requirements: Node.js 18 or newer (node -v to check) and git.
# 1. Clone the repo
git clone https://github.com/tanongkiat/mcp-chatgpt-file-store.git
cd mcp-chatgpt-file-store
# 2. Install dependencies
npm install
# 3. Build (optional — dist/ is committed, so a fresh clone already runs)
npm run buildVerify the install by starting the server over HTTP and hitting the health endpoint from a second terminal:
npm run start:httpcurl http://localhost:8080/health
# {"status":"ok","sessions":0}Ctrl+C stops it, or npm run stop from another terminal.
That's the whole install. Next: pick your sandbox folder (Setup), then connect a client — ChatGPT or Claude. Exposing the server beyond localhost? Read Authentication first.
mcp-chatgpt-file-store/
├── src/
│ ├── index.ts # entrypoint — stdio or HTTP mode
│ ├── http.ts # Streamable HTTP server (stateful sessions)
│ ├── server.ts # MCP server + tool registration
│ ├── filesystem.ts # sandboxed file operations + path safety
│ └── knowledge.ts # knowledge gathering + PlantUML flow extraction
├── scripts/
│ ├── generate-token.sh # create + save an auth token
│ ├── start-with-auth.sh # generate token and start the HTTP server
│ ├── start-daemon.sh # start detached (nohup + disown), logs to logs/
│ ├── stop.sh # stop the HTTP server by port
│ ├── setup-claude.sh # register this server with Claude
│ └── test-auth.sh # verify auth is enforced
├── dist/ # compiled output (committed, so no build needed to run)
├── Storage/ # default sandbox — <folder where server runs>/Storage
└── package.jsonDoc | Covers |
First run, start to finish | |
Shortest path to an authenticated server | |
Registering the server with Claude | |
How token auth works end to end | |
What each script in | |
Full OAuth 2.0 for multi-user setups | |
Project overview |
The server supports two transports — pick whichever your client wants:
Mode | Command | Endpoint |
stdio (default) |
| n/a (local process) |
Streamable HTTP |
|
|
By default the sandbox is <folder where the server runs>/Storage (i.e. the
Storage/ folder inside this project). To use your own folder(s), set an
environment variable:
export CHATGPT_FILE_STORE_DIRS="/path/to/my/notes,/path/to/another"npm run inspectThis opens the MCP Inspector where you can call each tool before wiring it to ChatGPT.
In ChatGPT, add a custom MCP server with this command:
node /absolute/path/to/mcp-chatgpt-file-store/dist/index.jsTip: point the command at the built
dist/index.js(notsrc), and use the absolute path. If you setCHATGPT_FILE_STORE_DIRS, make sure that environment variable is visible to the process ChatGPT launches.
Start the HTTP server (default port 8080):
npm run start:httpOr with a custom port/host:
node dist/index.js --http --port 9090 --host 0.0.0.0
# or via environment variables
MCP_HTTP_PORT=9090 MCP_HTTP=1 node dist/index.jsVia the npm script, pass flags after --:
npm run start:http -- --port 9090 --host 0.0.0.0Then register http://localhost:8080/mcp as the MCP server URL in ChatGPT.
Any MCP client works, not just ChatGPT. For Claude Desktop, run the interactive
setup script — it resolves the absolute path to dist/index.js, asks which
folder to sandbox, and writes the entry into claude_desktop_config.json:
./scripts/setup-claude.shRestart Claude Desktop afterwards, then confirm the server appears in its MCP server list. See CLAUDE_SETUP.md for the manual config.
For Claude Code, register it from the command line instead:
claude mcp add file-store -- node /absolute/path/to/mcp-chatgpt-file-store/dist/index.jsSet MCP_AUTH_TOKEN to require a Bearer token on every /mcp request:
MCP_AUTH_TOKEN=$(openssl rand -hex 32) node dist/index.js --httpThe server accepts tokens via two methods:
Authorization header (standard):
curl -H "Authorization: Bearer <token>" http://localhost:8080/mcpQuery parameter (convenient for some clients):
curl http://localhost:8080/mcp?token=<token>Both methods are validated using constant-time comparison for security. Requests
without a valid token receive 401 Unauthorized. The /health endpoint stays
open (no token needed) for liveness checks.
Query-parameter tokens land in browser history and proxy/nginx access logs in a way headers do not. Prefer the header wherever the client allows it.
Streamable HTTP is session-based, so a URL alone is not a connection.
POST /mcp with initialize mints a session and returns it in the
Mcp-Session-Id response header; every later request must present that id, via
the header or a ?session=<id> query parameter. GET /mcp only opens the SSE
stream for an existing session — it is not how you call the server.
This is why pasting the /mcp URL into a browser returns
Missing session: a browser sends a bare GET with no session, and it cannot
send Accept: text/event-stream either. Use /health for a browser-friendly
check, or drive the handshake with curl:
URL="http://localhost:8080/mcp?token=<token>"
SID=$(curl -s -D- -X POST "$URL" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
-o /dev/null | grep -i '^mcp-session-id' | tr -d '\r' | awk '{print $2}')
curl -s -X POST "$URL&session=$SID" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'A real MCP client does all of this for you — you only give it the URL.
When registering the connector in ChatGPT, add the token as a custom header:
Authorization: Bearer <token>.
If MCP_AUTH_TOKEN is not set, the server logs a startup warning and accepts
unauthenticated requests — fine for quick local testing, not for anything
reachable from the internet.
For full OAuth 2.0 implementation (multi-user scenarios), see OAUTH_GUIDE.md.
For the easiest way to start with authentication:
# Auto-generate token and start server
npm run start:authThis script will:
Generate a secure 64-character token
Save it to .mcp-token for reuse
Start the HTTP server with authentication
Display the token and usage examples
Or generate a token separately:
# Generate and save token
npm run generate-token
# Start server manually
source .env && npm run start:httpSee QUICKSTART.md for more details.
start:auth and start:http hold the terminal. To leave the server running
after you log out — the usual case on a VPS:
npm run start:daemonIt reuses the token from .mcp-token, starts the server under nohup and
disown so it survives SIGHUP, appends output to logs/mcp-server.log, and
writes the PID to .mcp-server.pid. It refuses to start if the port is already
taken, and reports the log tail if the server dies on startup instead of
leaving you with a silent failure.
npm run start:daemon -- --port 9090 --host 127.0.0.1
tail -f logs/mcp-server.log
npm run stopBoth logs/ and .mcp-server.pid are gitignored.
For a machine that reboots, prefer a real supervisor (
systemdon Linux,launchdon macOS) —nohupsurvives logout, not restarts.
start:auth and start:http run in the foreground, so Ctrl+C stops them. If
the server is running detached or in another terminal, stop it by port:
npm run stop # stops the server on port 8080
npm run stop -- --port 9090 # a different port
npm run stop -- --force # SIGKILL if it ignores SIGTERMIt sends SIGTERM first, waits up to 5 seconds for the port to free, and
exits 0 if nothing was listening.
The server implements the MCP Streamable HTTP transport:
POST /mcp — JSON-RPC requests (first call creates a session and returns a
Mcp-Session-Id header; send it back on subsequent requests)
GET /mcp — SSE stream for server-initiated messages
DELETE /mcp — ends a session
GET /health — liveness check ({"status":"ok","sessions":N})
/login → /mcp/browse)In addition to the JSON-RPC API, the HTTP server serves a small password-protected
file browser so you can view /Storage from a normal web browser:
GET /login — login form (username + password)
POST /login — validates credentials, then sets an HttpOnly session cookie
GET /mcp/browse — the authenticated file browser for /Storage
GET /mcp/browse?path=docs — navigate into a subfolder
GET /mcp/browse?view=notes.md — view a file's contents
GET|POST /logout — clears the session cookie
Authentication is username/password (separate from the MCP bearer token), not
OAuth. Sessions are HttpOnly, SameSite=Lax cookies signed with an HMAC key.
Every path is still resolved through the same sandbox as the MCP tools, so an
authenticated user can never read or navigate outside the allowed directories.
Configuration (all optional — sensible defaults apply):
Variable | Default | Notes |
|
| Login username |
| falls back to | Login password |
| falls back to | HMAC key for session cookies |
If neither MCP_BROWSE_PASSWORD nor MCP_AUTH_TOKEN is configured, web login is
disabled (the server logs a warning). When using start:auth or start:daemon,
MCP_AUTH_TOKEN is already exported, so you can log in with username admin and
your bearer token as the password.
# Quick manual start with explicit credentials
MCP_BROWSE_USER=admin MCP_BROWSE_PASSWORD=secret \
node dist/index.js --http --port 8080
# Then open http://localhost:8080/mcp/browseget_knowledge reads everything in the store at once, rather than making the
model open files one by one:
get_knowledge({
"query": "auth", // optional: only docs whose path or text matches
"format": "auto", // "auto" | "markdown" | "plantuml"
"max_bytes": 100000 // budget across all documents
})Formats:
markdown — every document concatenated under ## path/to/file.md headings.
plantuml — diagrams only. A document yields a diagram three ways:
an existing @startuml block or ```plantuml fence is passed through
unchanged; two or more A -> B: label lines become a sequence diagram;
two or more numbered steps become an activity diagram.
auto (default) — Markdown, with a PlantUML section prepended when any
document describes a flow.
So 1. User submits the form / 2. Service validates the email turns into:
@startuml
start
:User submits the form;
:Service validates the email;
stop
@endumlBinary files and unknown extensions are skipped, and files are read through the same sandbox checks as every other tool.
The extraction is deterministic pattern-matching, not interpretation — it finds flows that are already written as diagrams, arrows, or numbered steps. For prose that merely implies a process, use
format: "markdown"and let the model author the diagram.
Once connected, you can tell ChatGPT things like:
"Save the summary of our conversation to notes/summary.md"
"Append today's ideas to ideas.md"
"List everything in the projects folder"
"Search for files containing draft in the name"
Every path is resolved and checked against the allowed roots before any operation.
.. traversal and paths outside the roots are rejected with an error.
In stdio mode the server exposes no network port at all.
In HTTP mode the server binds to 0.0.0.0:8080 by default — use
--host 127.0.0.1 to restrict it to localhost only. Sessions are tracked by
random UUID. Set MCP_AUTH_TOKEN (see Authentication above) before exposing
this server beyond localhost — without it, anyone who finds the URL can
read/write files in the sandbox.
Only the configured directory is readable/writable — treat the sandbox as not secret (ChatGPT content is processed by the model provider).
npm run build # compile TypeScript
npm run watch # recompile on change
npm run start # run compiled server over stdio
npm run start:http # run compiled server over Streamable HTTP (port 8080)
npm run start:auth # generate a token and start the HTTP server with auth
npm run start:daemon # start detached (survives logout), logs to logs/
npm run stop # stop the HTTP server (SIGTERM, then --force for SIGKILL)
npm run generate-token # create a token and save it to .mcp-token
npm run dev # run stdio mode with tsx (no build step)
npm run dev:http # run HTTP mode with tsx (no build step)
npm run inspect # open MCP Inspector UIAppends content to an existing file, or creates the file if it does not exist. Use this to keep growing a running log or notes file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to append to | |
| content | Yes | Content to append (add your own newline if needed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavior disclosure. It states the file is created if it doesn't exist, which is a key side effect, but does not mention error conditions, return value, or permission requirements. It adds some transparency but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action and followed by a use case. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the primary behavior and a use case. It could mention sibling alternatives or edge cases like not creating intermediate directories, but it is still adequately complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for path and content. The description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'appends' with the resource 'file' and clarifies the file is created if absent, clearly distinguishing from siblings like write_file which overwrites. It names the action and scope precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this to keep growing a running log or notes file' provides an explicit use case, but does not explicitly exclude alternatives like write_file or mention when not to use it. This is clear context without formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a folder (and any missing parents) inside the file store.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Directory path to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a key behavioral detail: missing parent directories are also created. However, no annotations exist, so the description carries the full burden. It does not disclose behavior for existing directories, error handling, or permission requirements, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It is front-loaded with the action and immediately provides a crucial nuance ('and any missing parents'), earning its place without excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one parameter and no output schema, the description is mostly sufficient. It states the action and the main side-effect (parent creation). However, it omits behavior for existing directories and lacks reference to related tools like list_allowed_directories, which could be useful in a broader context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers the path parameter (100% coverage), the description enriches its meaning by stating that missing parents are created. This implies the path can be nested and is not limited to a leaf directory, which the generic schema description does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates a folder inside the file store, with a specific verb ('creates') and resource ('folder'). Distinguishes from sibling file operations by targeting directories and noting the recursive parent creation behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like write_file or delete_file. It provides a general idea (create a directory) but lacks conditions, prerequisites (e.g., checking allowed directories), or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently deletes a file or folder (recursively) from the file store. Use with care.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses critical behavioral traits: permanence ('Permanently deletes') and recursive folder deletion, plus a caution. However, it omits details like error handling or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences: the first is dense with action, resource, and scope; the second is a clear caution. No redundancy or filler, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers the operation, recursive behavior, permanence, and a caution. No critical details are missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the path parameter described as 'Path to delete', so the baseline of 3 applies. The description adds no extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Permanently deletes a file or folder (recursively)' with a specific verb and resource. It distinguishes from siblings like move_file and write_file, which are non-destructive operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The warning 'Use with care' implies caution but does not provide context on when deletion is appropriate or what conditions should be checked first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns metadata (size, modified time, permissions) for a path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path inside the file store |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly indicates a read-only operation that returns metadata, but it does not mention error handling (e.g., path not found), symlink behavior, or permission requirements. It is adequate for a simple read tool but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that conveys the tool's purpose and return fields without waste. Front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the main output (metadata fields) adequately. However, it does not describe error conditions or provide guidance on when to choose this over sibling tools, leaving a small gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter ('path') with its own description. The tool description adds no additional parameter semantics beyond the schema, so it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns metadata') and identifies the resource ('a path'), listing concrete attributes (size, modified time, permissions). This clearly differentiates it from siblings like read_file (content) and list_directory (directory entries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when metadata is needed, but it does not explicitly state when to use this tool over alternatives like read_file or list_directory. No exclusions or alternative scenarios are mentioned, so it relies on the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the directories ChatGPT is allowed to read from and write to. Call this first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the burden of behavioral disclosure. It accurately conveys a read-only operation ('returns') and adds context about the read/write permission scope. No side effects or hidden behaviors are expected for a tool that simply lists allowed directories, so the description sufficiently discloses what the tool does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence plus a short imperative, using 13 words total. It is front-loaded with the core function and ends with a clear instruction. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description covers the essential information: what it returns and when to call it. It does not describe the format of the returned directories, but that is a minor gap for this type of tool. The guidance is sufficient for a competent agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed. It correctly avoids mentioning parameters that do not exist, and the tool's function is self-contained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the directories ChatGPT is allowed to read from and write to, using a specific verb ('returns') and resource ('directories'). It distinguishes itself from sibling file-operation tools, and the phrase 'Call this first' indicates a unique role for the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an explicit directive 'Call this first,' which tells the agent when to invoke the tool. It does not mention alternatives or exclusions, but the tool is distinct from its siblings and its position as a first step is clearly implied. This provides adequate usage guidance for a simple discovery tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists files and folders inside a directory within the allowed store.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Directory path inside the file store |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the operation is a listing and mentions the 'allowed store' restriction, but it does not disclose error behavior, return format, or edge cases like empty directories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words that front-loads the verb 'Lists'. Every word adds value, with no redundancy or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one required parameter and no output schema. The description covers the basic purpose and constraint but lacks details on return structure (e.g., array of names) and error handling. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'path' parameter as 'Directory path inside the file store'. The description adds the 'allowed store' context, but this is only a slight reinforcement; baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lists files and folders inside a directory', which is a specific verb and resource. It distinguishes itself from siblings like read_file (content), get_file_info (metadata), and search_files (search) by focusing on directory contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when needing directory listing) but does not explicitly mention alternatives or exclusions. It does provide a constraint ('within the allowed store'), but no comparison with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moves or renames a file or folder inside the file store.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Existing path | |
| destination | Yes | New path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but only states the operation. It does not disclose overwrite behavior, path constraints, recursion, or reversibility of the move operation, which is significant for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The lack of annotations and output schema means the description must provide comprehensive context, but it only covers the basic operation. Missing details like overwrite behavior or handling of existing destinations leave significant gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions for source and destination are clear ('Existing path' and 'New path') with 100% coverage. The description adds no additional parameter-level meaning, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Moves or renames' and identifies resource 'file or folder inside the file store,' clearly distinguishing it from siblings like delete_file, write_file, and read_file. The title echoes the description, reinforcing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to use move vs rename or copy. No exclusions or alternative tool references are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the full contents of a text file inside the allowed file store.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path inside the file store |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only says it reads full contents of a text file, but omits important behavioral details such as what happens if the file is binary, size limits, encoding assumptions, or whether the operation is safe/non-mutating. The word 'reads' implies non-destructiveness, but that is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused, front-loaded sentence. There is no wasted wording, and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is adequate but not complete. It lacks information about return format, error handling, or limitations (e.g., file size, binary support). While the tool is inherently simple, the absence of annotations and output schema means the description should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds context about 'full contents' and 'allowed file store' which aligns with the 'path' parameter, but it does not provide additional meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reads'), the resource ('a text file'), and the scope ('full contents' and 'inside the allowed file store'). It distinguishes itself from sibling tools like get_file_info (which likely returns metadata) and search_files (which searches), making the purpose immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need the full content of a text file, but it does not explicitly mention when not to use it or suggest alternatives like get_file_info or search_files. Usage context is somewhat inferable from the wording, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches the file store for files matching a pattern (supports * and ?).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Directory to search inside | |
| pattern | Yes | Glob pattern, e.g. *.md or *notes* | |
| recursive | No | Search subdirectories (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only discloses wildcard support, omitting critical behaviors like default recursion (true per schema), return format (paths vs. file objects), handling of hidden files, and case sensitivity. This leaves significant behavioral ambiguity for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the core purpose and key feature (wildcard support) without any filler or redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the search returns (e.g., list of paths, file objects) but does not. It also lacks context on edge cases and operational details like recursion behavior, making it incomplete for a tool that an agent must invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds a small note about wildcards (* and ?), which slightly supplements the schema's 'Glob pattern' example, but it does not provide meaningful additional semantics for the parameters beyond what the schema already defines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'searches' and clearly identifies the resource 'file store' with a pattern-matching function. It distinguishes itself from sibling tools like list_directory and read_file by focusing on pattern-based search rather than direct listing or reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pattern-matching scenarios but does not explicitly mention when to avoid this tool or name alternatives. It relies on the user to infer that search is appropriate when a pattern is known, but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates or overwrites a file in the file store. Parent folders are created automatically. Use this to save notes, drafts, summaries, or generated documents.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Destination file path, e.g. notes/idea.md | |
| content | Yes | Full content to write to the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states overwrite semantics and automatic parent folder creation, which are important behavioral details beyond the input schema. It does not mention permissions or return values, but core behavior is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and contains no filler. Every sentence contributes useful information about purpose, behavior, or usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, two fully described parameters, and no output schema, the description is complete. It covers the action, overwrite behavior, automatic parent folder creation, and concrete use cases, leaving no significant gaps for an agent to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters with 100% coverage. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Creates or overwrites a file in the file store.' It clearly distinguishes this from sibling tools like append_file (appends), move_file (moves), and delete_file (deletes), and it specifies the exact action and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: 'Use this to save notes, drafts, summaries, or generated documents.' This tells the agent when the tool is appropriate, but it does not explicitly mention alternatives or edge cases like when to use append_file instead of overwriting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0append_filecreate_directorydelete_fileget_file_infolist_allowed_directorieslist_directorymove_fileread_filesearch_fileswrite_fileScored across 10 tools
Each tool targets a distinct file operation: move, delete, append, read, write, list, search, metadata, directory creation, and allowed-directory listing. There is no functional overlap that could confuse an agent.
All tool names follow the verb_noun pattern in snake_case (e.g., move_file, list_directory, get_file_info). The naming is uniform and predictable across the entire set.
With 10 tools, the server covers the essential file operations without bloat. Each tool serves a clear purpose and the count feels appropriate for a file store MCP server.
The surface covers create, read, update, delete, move, search, and metadata operations. One notable gap is the absence of a copy_file operation, which would round out the file management capabilities, but existing coverage is solid.
Browse and manage files in your Moxt AI workspace from any MCP client.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Manage portable AI agent playbooks, Agent Skills, MCP configurations, personas, and memory.
