MCP Client Template

This is a base template for MCP (Model Context Protocol) client projects, featuring a Vite + TypeScript frontend and an Express backend. It allows you to add, manage, and interact with MCP servers via a web interface.

OAuth2.1 support: The template natively supports OAuth2.1 authentication for secure access and integration, as described in the official documentation.

OAuth2.1 Authentication Flow

When connecting to an MCP server that requires authentication, the frontend will provide an authentication link. Follow these steps:

1. Attempt to connect to the server from the web interface.
2. If authentication is required, a link will appear in the frontend.
3. Copy the link and paste it into a new tab in your browser.
4. Complete the authentication process in the new tab (OAuth2.1 redirect flow).
5. Once authenticated, return to the MCP Client Template interface to continue using the server.

This manual copy-paste flow is present because this project is only a template.

Project Structure

• public/: Static files and resources (favicon, images, OAuth callback).
• src/: TypeScript frontend and CSS.
  • main.ts: UI logic for adding servers, sending commands, and displaying output.
  • style.css: Interface styling.
• server/: Express backend.
  • index.ts: REST API for MCP server management, command forwarding, authentication handling.
  • authTokensStore.ts, mcpTypes.ts: Token management and MCP types.
• index.html: Main page structure.
• package.json: Dependencies and scripts (dev, build, preview, server startup).
• tsconfig.json: TypeScript configuration.

The data/ folder contains runtime memory and configuration and should not be modified manually.

Requirements

• Node.js (recommended version >=18)

Installation

1. Clone the repository:

   git clone <url-repo>
   cd mcp-client-template

2. Install dependencies:

   npm install

Development & Usage

• Start the frontend:

  npm run dev

• Start the backend:

  npm run dev:server

Customization & Extension

• To add new frontend features, edit files in src/.
• To extend the backend, work in server/.
• You can add new endpoints, authentication logic, and advanced MCP server management.

Forking & Reuse

You are encouraged to fork this repository to use it as a starting point for your own MCP client projects. After forking:

• Rename the project and update metadata as needed in package.json and documentation files.
• Customize the frontend and backend logic to fit your requirements.
• Remove or adapt example code and endpoints as needed.

This template is designed to be easily extended for more complex MCP projects.

Additional Notes

• The data/ folder is ignored and should not be manually edited.

---

For questions or suggestions, open an issue or contact the maintainer.