mcp-front

mcp-front acts as an authentication gateway between Claude and your MCP servers. It provides per-user isolation by spawning dedicated subprocesses for stdio-based servers and handling per-service tokens (for services like Notion or Linear) via a user-facing web UI. In practice, you configure mcp-front with your MCP server definitions and an OAuth identity provider, then Claude connects to your gateway endpoint to access the underlying MCP services without exposing them directly to the internet. The example in the README demonstrates a filesystem-backed MCP server powered by the Model Context Protocol: users authenticate once, and mcp-front proxies requests to the actual backend over a secure, isolated channel. The server-frontend (mcp-front) itself can be run via Go, or via Docker, while the backend MCP servers are invoked via tools like npx for stdio-based components.

To use it locally, configure MCP servers in a config.json (as shown in the example), start mcp-front with that config, and point Claude (or your client) to http://localhost:8080/your-service/sse. This will trigger the OAuth login flow, token validation, and per-user routing to the appropriate backend server. If you’re using the provided filesystem example, the inner server is started with npx -y @modelcontextprotocol/server-filesystem /tmp, enabling a local filesystem-backed MCP endpoint for testing.

Prerequisites:

• A supported host with Go installed (for building the mcp-front binary) or Docker if you prefer running via container
• Node.js and npm if you plan to access certain MCP servers via npx tooling (as shown in the example)
• Docker if you want to run the gateway in a container

Install steps (Go-based build):

1. Install Go (https://golang.org/dl/)
2. Build and install mcp-front: go install github.com/stainless-api/mcp-front/cmd/mcp-front@main
3. Prepare a config.json as in the README example under your project directory.
4. Run the gateway: mcp-front -config config.json

Alternative: Run the provided backend server using npx and docker as demonstrated in the README:

• Local backend (example): npx -y @modelcontextprotocol/server-filesystem /tmp
• Docker run (gateway should be configured to reference your config.json): docker run -p 8080:8080 -v <path-to-config>/config.json:/app/config.json dgellow/mcp-front:latest

If you prefer Docker for the gateway only, ensure your config.json is mounted into the container so mcp-front can read the mcpServers definitions.

Tips and caveats:

• This project is described as alpha software in the README. Expect breaking changes as features evolve.
• The example config uses a Bearer token for service authentication (dev-token-123). Replace or remove tokens as appropriate for production.
• Per-user isolation is implemented for stdio-based servers by spawning dedicated subprocesses per user. Ensure your environment supports subprocess management and that resource limits are appropriate.
• For services requiring API keys or OAuth tokens (e.g., Notion, Linear), users will need to connect those services through a web UI provided by mcp-front; tokens are then injected per user/session.
• Review the architecture docs and API reference linked in the README to understand audience validation, token claims, and per-service audience handling (RFC 8707).
• If you switch between Go-based builds and Docker, keep your config.json in sync with the expected paths and ensure network access from Claude to your gateway URL.