# 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.

```text
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

```bash
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.

```bash
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

```bash
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.