mcp-container-ts

This MCP server implements a Node.js/TypeScript-based HTTP MCP endpoint that hosts a set of tools (for example, a simple to-do list) and exposes them through authenticated MCP calls. Clients must first obtain a JWT with an appropriate role (admin, user, or readonly) and then use the MCP HTTP interface to interact with available tools. The server demonstrates a multi-layer security setup combining JWT-based authentication with RBAC to control access to endpoints and tools. Tools such as adding, listing, completing, and deleting to-dos are backed by a SQLite database and can be extended with additional functionality in the tools module. To use, generate a token, start the server, and send MCP requests to the endpoint (e.g., /mcp) with the token provided in the Authorization header. The example in the repository shows how the server initializes its database, starts the stateless streamable HTTP server, and exposes the MCP endpoint for clients to interact with.

Prerequisites

• Node.js v22 or higher
• npm (comes with Node.js)
• Git

Install and run locally

1. Clone the repository

git clone https://github.com/Azure-Samples/mcp-container-ts.git
cd mcp-container-ts

2. Install dependencies

npm install

3. Generate a JWT configuration (optional but recommended for testing)

npm run generate-token -- --admin

This will append or create a new JWT configuration in the root .env file. You can choose roles like --admin, --user, or --readonly to set permissions accordingly. 4) Start the MCP server in development mode

npm run dev

The server will initialize the SQLite database, start the MCP endpoint, and print a URL such as http://localhost:3000/mcp. You can then use the generated JWT to authenticate and exercise the exposed tools. Note: In production, configure a secure environment, manage secrets properly, and consider deploying via your chosen platform (Azure Container Apps, etc.).

Tips and common considerations:

• Ensure JWT_SECRET is kept secure; use environment-managed secrets in production.
• The MCP endpoint is typically served at /mcp; include the JWT in the Authorization header as a Bearer token when making requests.
• The example uses SQLite for a lightweight local database; you can replace or extend the storage backend as needed.
• If you modify code or environment variables, restart the server to apply changes.
• Port configuration can be adjusted via the PORT environment variable.
• For debugging, enable verbose logs by adjusting MCP_LOG_LEVEL in env.
• If you encounter token-related errors, re-generate the token with the desired role and ensure the token is included in requests.