prompts/docs/securing.md

icon

icon
lucide/shield-check

Securing Remote Access

Context

This project exposes two related surfaces from the same runtime:

1. a static documentation site under /docs
2. a Streamable HTTP MCP endpoint under /mcp

The same Markdown content backs both surfaces. For the current project shape, the MCP server is resource-first and primarily exposes public skill and documentation text. It is not intended to expose secrets, private data, shell access, filesystem access, or tools with side effects.

The expected deployment path is:

Public internet
	-> Cloudflare Tunnel
	-> Caddy
	-> personal-mcp container

Decision

For the current use case, heavy application-level authentication is not required.

The recommended posture is:

1. Keep the service behind Cloudflare Tunnel and Caddy.
2. Do not expose the container port directly to the public internet.
3. Treat everything exposed through MCP as publishable public documentation.
4. Add stronger authentication only if the MCP surface later includes sensitive content or tools with meaningful side effects.

This keeps the deployment simple while preserving a clear upgrade path.

Tradeoffs

Leaving /mcp Public

This is acceptable if /mcp exposes only the same public Markdown already available through /docs.

Benefits:

1. lowest operational friction
2. fewer compatibility issues with MCP clients
3. no need to implement OAuth, mTLS, JWT validation, or custom auth middleware
4. consistent with the project assumption that documentation content is public

Risks:

1. random scraping, probing, or fuzzing of a machine endpoint
2. possible bandwidth or CPU nuisance traffic
3. accidental future exposure if new tools or private resources are added
4. less control over who can use the MCP endpoint

Protecting /mcp With Cloudflare Access

Cloudflare Access can add a lightweight gate using GitHub, Google, one-time PIN, or service tokens.

Benefits:

1. reduces random internet traffic
2. requires little app code
3. works well for a small trusted team
4. provides logs and centralized access control

Costs:

1. browser-based login may not work with all MCP clients
2. non-browser MCP clients may need Cloudflare Access service tokens
3. adds operational configuration for a low-sensitivity endpoint

Using mTLS

mTLS is useful when both client and server environments are tightly controlled.

Benefits:

1. strong client identity
2. good fit for service-to-service or private infrastructure
3. can be used between Cloudflare, Caddy, and the backend if desired

Costs:

1. harder certificate provisioning and rotation
2. weaker compatibility with normal MCP clients
3. unnecessary for public documentation-only content

For this project, mTLS is not the primary recommendation.

Practical Recommendation

Use a simple public-docs posture unless the endpoint changes.

Recommended current setup:

/docs  public
/mcp   public or lightly protected

If /mcp remains public, add only basic operational safeguards:

1. keep Cloudflare Tunnel and Caddy in front
2. avoid publishing 8765 directly
3. enable Cloudflare or Caddy rate limiting if traffic becomes noisy
4. monitor logs for unusual request volume
5. document that MCP resources must remain safe to publish

A slightly stricter setup is also reasonable:

/docs  public
/mcp   Cloudflare Access or service token

This is the best option if the team wants to reduce drive-by MCP traffic without adding auth code to the application.

Upgrade Trigger

Add real authentication before introducing any MCP capability that can:

1. read non-public files
2. access private notes or credentials
3. call upstream APIs
4. mutate data
5. run commands
6. expose environment details
7. perform expensive computation

At that point, prefer edge-level authentication first, such as Cloudflare Access, and consider proper OAuth 2.1 resource-server behavior only if broad public MCP client interoperability becomes a goal.

Security Invariant

Everything exposed by the MCP server must be safe to publish publicly.

If that invariant stops being true, /mcp should be protected before the new capability is deployed.