LanternFS - Secure Filesystem MCP

LanternFS is a remote filesystem MCP server that lets MCP clients such as ChatGPT access a controlled local directory.

It protects the remote MCP endpoint with OAuth, so exposing the server through ngrok does not mean that anyone who discovers the public URL can access the filesystem.

Security model

ChatGPT
   |
   | OAuth
   v
LanternFS
   |
   | Valid access token
   v
MCP endpoint
   |
   v
Filesystem tools
   |
   v
ALLOW_ROOTS

The password is used only during the OAuth authorization step. It is not used as the MCP access token and is never sent to the MCP tools.

Features

• OAuth authorization for remote MCP clients.

• Designed for ChatGPT OAuth MCP connections.

• Password-only authentication or optional username and password.

• Authorization Code flow with S256 PKCE.

• Short-lived access tokens.

• Long-lived rotating refresh tokens.

• OAuth discovery and metadata through the MCP TypeScript SDK.

• Protected Streamable HTTP MCP endpoint.

• Configurable filesystem roots.

• ngrok HTTPS tunnel support.

• Secrets excluded from Git.

Setup

1. Install Node.js

Use a current supported Node.js release.

node --version
npm --version

2. Clone the repository

git clone https://github.com/deviprasadshetty-dev/filesystem-mcp.git
cd filesystem-mcp
npm install

3. Create the environment file

Copy the example file:

Copy-Item .env.example .env

Open it:

notepad .env

4. Configure the filesystem root

The ALLOW_ROOTS setting controls which directories LanternFS can access.

For a safe setup, create a dedicated workspace:

New-Item -ItemType Directory -Force D:\mcp-workspace

Then use:

ALLOW_ROOTS=D:\mcp-workspace

Avoid exposing an entire drive unless you intentionally need it:

ALLOW_ROOTS=D:\

OAuth controls who can connect, while ALLOW_ROOTS controls what an authorized client can access. You should use both.

5. Configure the OAuth password

Set a strong password in .env:

MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

The password must be at least 16 characters.

You can optionally configure a username:

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

If MCP_AUTH_USERNAME is empty, LanternFS uses a password-only login page.

If a username is configured, both username and password must match.

How the password is used

You do not enter this password into ChatGPT's MCP settings.

When ChatGPT connects for the first time, it starts the OAuth authorization flow and opens the LanternFS login page.

Enter the same credentials that you configured in .env:

Username: deviprasad
Password: ********

[ Authorize ]

After successful authorization, ChatGPT receives an OAuth authorization code and exchanges it for an access token and refresh token.

The password is not sent to /mcp.

6. Configure ngrok

LanternFS needs a public HTTPS URL so that ChatGPT can reach the MCP server.

The project can use an ngrok authtoken from either of these locations:

Recommended: ngrok local configuration

Authenticate ngrok normally on your machine using the ngrok CLI and keep the token in ngrok's own configuration.

For example:

ngrok config add-authtoken YOUR_NGROK_TOKEN

You do not need to put the ngrok token in .env when it is already configured locally.

Alternative: .token file

LanternFS also supports a local .token file containing only the ngrok authtoken:

YOUR_NGROK_TOKEN

The .token file is ignored by Git.

Alternative: environment variable

You can also provide:

NGROK_AUTHTOKEN=YOUR_NGROK_TOKEN

This is optional. Do not add it to .env unless you specifically want LanternFS to receive the token through the environment.

Configure the ngrok domain

For a stable URL, set your ngrok domain:

NGROK_DOMAIN=your-domain.ngrok-free.app

If NGROK_DOMAIN is empty, ngrok can use an ephemeral URL when supported by your account/configuration. A stable domain is recommended for a persistent ChatGPT MCP connection.

7. Example .env

A recommended setup looks like this:

PORT=3000
ALLOW_ROOTS=D:\mcp-workspace
NGROK_DOMAIN=your-domain.ngrok-free.app

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

Notice that NGROK_AUTHTOKEN is not required here when ngrok is already authenticated locally.

Never commit .env or .token.

Run LanternFS

Check the project first:

npm run build
npm test

Then start the server:

npm start

The server starts the local MCP HTTP service and creates the ngrok HTTPS tunnel.

The console prints the public URL.

Keep the process running while ChatGPT needs the MCP connection.

Recommended MCP client description

When adding LanternFS to an MCP client, use the following description so the client knows when it should use this server:

LanternFS provides access to my local filesystem and project files. Use this MCP whenever a task involves files, folders, source code, repositories, documents, or other data that may exist on my local computer. Prefer LanternFS over guessing or asking me to paste file contents when the required files are available locally. Do not use it for information that does not require access to my local filesystem.

This description is intended for the MCP client's server description or tool-use guidance. It tells the client to prefer LanternFS for local-file tasks while avoiding unnecessary use for general knowledge or web-based tasks.

Connect to ChatGPT

1. Start LanternFS with npm start.

2. Copy the public HTTPS MCP URL printed in the console.

3. Add a remote MCP connector in ChatGPT.

4. Select OAuth as the authentication method.

5. Enter the LanternFS MCP URL.

6. ChatGPT performs OAuth discovery.

7. Your browser opens the LanternFS authorization page.

8. Enter the username and password from .env.

9. Click Authorize.

10. ChatGPT completes the OAuth flow and connects to /mcp.

You should only need to enter the password when a new authorization is required.

Persistent connection

LanternFS does not use a permanent access token.

The current implementation uses:

• Access tokens that expire after a short period.

• Long-lived refresh tokens that allow the client to obtain new access tokens.

• Refresh-token rotation when a refresh token is used.

• The configured password only for initial authorization.

This lets ChatGPT remain authorized without asking for the password every time while avoiding a permanent filesystem access token.

Deleting .oauth-state.json resets the locally stored OAuth state and requires clients to authorize again.

OAuth endpoints

LanternFS uses the authorization interfaces provided by the installed MCP TypeScript SDK.

Security recommendations

Use a strong password

Use a unique random password of at least 16 characters.

For example, PowerShell can generate random bytes:

[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Maximum 256 }))

Do not copy an example password into production.

Restrict the filesystem

Prefer:

ALLOW_ROOTS=D:\mcp-workspace

over:

ALLOW_ROOTS=D:\

Protect secrets

Never commit:

.env
.token
.oauth-state.json

Before pushing changes:

git status
git diff --cached

Never force-add these files.

Protect your ngrok account

If an ngrok authtoken is exposed, rotate it through your ngrok account.

Stop remote access when it is not needed

Stopping LanternFS stops its HTTP MCP endpoint and ngrok tunnel.

Troubleshooting

ChatGPT cannot complete OAuth discovery

Check that:

• LanternFS is running.

• ngrok is authenticated.

• The ngrok tunnel is active.

• The public URL uses HTTPS.

• NGROK_DOMAIN is correct if you configured one.

The password is rejected

Check .env and restart LanternFS after changing it.

If MCP_AUTH_USERNAME is configured, both username and password must match.

ChatGPT asks for authorization again

Check that .oauth-state.json still exists and has not been deleted or replaced.

A reset of the OAuth state intentionally requires authorization again.

A filesystem path is unavailable

Check ALLOW_ROOTS and make sure the requested path is inside one of the configured roots.

Development

npm install
npm run build
npm test
npm start

npm run build performs a TypeScript type check.

npm test runs the filesystem self-check.

References

LanternFS is built around the authorization architecture provided by the Model Context Protocol TypeScript SDK and the relevant OAuth standards.

• MCP Authorization specification: https://modelcontextprotocol.io/specification/draft/basic/authorization

• MCP TypeScript SDK: https://ts.sdk.modelcontextprotocol.io/

• MCP client registration guidance: https://blog.modelcontextprotocol.io/posts/client_registration/

• RFC 8414 - OAuth 2.0 Authorization Server Metadata: https://www.rfc-editor.org/rfc/rfc8414

• RFC 9728 - OAuth 2.0 Protected Resource Metadata: https://www.rfc-editor.org/rfc/rfc9728

• RFC 7636 - Proof Key for Code Exchange (PKCE): https://www.rfc-editor.org/rfc/rfc7636

• RFC 7009 - OAuth 2.0 Token Revocation: https://www.rfc-editor.org/rfc/rfc7009

MCP authorization behavior can evolve as the specification develops. Keep the MCP TypeScript SDK updated and review its authorization documentation when upgrading the project.

License

Add a license before publishing LanternFS for broad reuse.