Notion local filesystem MCP pilot

This project verifies a narrow path from a remote MCP client to a local file without syncing that file to GitHub, Google Drive, or another content store.

remote MCP client
  -> HTTPS tunnel
  -> Bearer-authenticated Streamable HTTP gateway on 127.0.0.1
  -> official filesystem MCP over stdio
  -> one explicitly allowed local directory

The default verification root is fixtures/allowed/. Global Codex configuration and Notion configuration remain unchanged.

Components

• @modelcontextprotocol/server-filesystem@2026.7.10
• @modelcontextprotocol/sdk@1.29.0
• express@5.2.1
• cloudflared@2026.7.2 installed with Homebrew

Verify locally

npm install
npm run verify

npm run verify runs two checks:

1. Direct stdio verification of the official filesystem server
2. Streamable HTTP verification through the read-only gateway

Verified on 2026-07-18 with Node v26.0.0 and npm 11.12.1:

• MCP initialization over stdio: passed
• Official filesystem tools discovered: 14
• Gateway tools exposed: 6 read-only tools
• Bearer authentication: required
• Untrusted browser Origin: blocked
• Allowed file read: passed
• Direct outside-root read: blocked
• Outside-root symlink traversal: blocked
• Sensitive credential-like file read: blocked
• Sensitive allowed root: rejected
• Sensitive entries in tree and search tools: excluded
• Write tool omitted and direct write call: blocked
• Dead upstream readiness: 503
• Public HTTPS MCP read through a temporary tunnel: passed
• Temporary tunnel and gateway shutdown after the check: passed
• npm audit --omit=dev: 0 vulnerabilities

Run the local HTTP gateway

The gateway refuses to start unless the root is absolute and the token contains at least 32 characters.

export MCP_ALLOWED_ROOT="/absolute/path/to/one/allowed/directory"
export MCP_BEARER_TOKEN="<strong-random-secret>"
export MCP_PORT="8765"
npm run start:http

The MCP endpoint is http://127.0.0.1:8765/mcp. The unauthenticated health endpoint is http://127.0.0.1:8765/healthz and returns no filesystem path or tool details.

Do not save the bearer token in this repository or include it in command-line arguments.

Verify through an ephemeral public tunnel

npm run verify:tunnel

The tunnel verifier generates an in-memory token, opens a temporary trycloudflare.com tunnel to the sample root, repeats the MCP checks through public HTTPS, and terminates both processes. It does not print the token or temporary URL. On this Mac, the local DNS resolver did not consistently resolve temporary tunnel hostnames, so the verifier resolves them with public DNS and pins the returned address only for each test request.

Quick Tunnel has no stable hostname or uptime guarantee and does not support SSE. The gateway therefore uses stateless Streamable HTTP with JSON responses. A persistent Notion connection should use a named tunnel or another stable HTTPS endpoint.

Security boundary

The upstream official server exposes ten read tools plus write_file, edit_file, create_directory, and move_file. It has no server-side read-only CLI switch. This gateway exposes only these tools:

• read_text_file
• list_directory
• directory_tree
• search_files
• get_file_info
• list_allowed_directories

Unknown or write-capable tool calls are rejected before they reach the upstream server. read_multiple_files is omitted to limit bulk reads, and list_directory_with_sizes is omitted because its current upstream implementation can follow an external symlink while collecting metadata. The upstream server separately enforces the allowed root, and the upstream process runs under a macOS sandbox that denies all file writes.

The gateway refuses an allowed root inside .git, .ssh, .aws, or .gnupg, and denies direct reads of those directory trees, .env*, common private-key/certificate extensions, and common credential file names. Recursive tree and search calls automatically exclude the same high-risk entries. Text reads default to 400 lines, cap at 2,000 lines, and reject files larger than 5 MB.

The gateway binds only to 127.0.0.1, validates the HTTP Host, rejects unconfigured browser origins, uses constant-time bearer comparison, allows at most two concurrent calls, applies a 15-second tool timeout, limits text reads and responses, and does not log request headers or tokens. If the upstream process dies or a call times out, readiness changes to 503 and the dedicated upstream is stopped; restart the gateway before retrying.

Do not expose /Users/seokmogu/project as a single root. Select the smallest directory needed by one private Notion Custom Agent. Files returned by an MCP tool leave the Mac and are processed by Notion even though they are not synchronized to another storage service.

Current limitations

• The static bearer token is suitable for a private pilot, not a replacement for OAuth lifecycle management.
• The public Quick Tunnel check depends on an account-less external service with no SLA.
• A stable Notion connection still needs a persistent HTTPS hostname and an explicitly selected Custom Agent.
• No Notion workspace or Custom Agent configuration is changed by this pilot.
• The official Inspector CLI 0.22.0 fails on the local Node v26.0.0 runtime because it cannot resolve its own cli/package.json; verification uses the official SDK client instead.