ngsanthosh/typescript-mcp-auth-quickstart

Secure MCP TypeScript Server

A TypeScript-based Model Context Protocol (MCP) server with OAuth2 authentication powered by Asgardeo.

Overview

This project demonstrates how to create a secure MCP server that:

• Uses TypeScript for type safety
• Implements OAuth2 authentication with Asgardeo
• Exposes MCP tools that require authentication
• Returns authenticated user profile information

Prerequisites

• Node.js (v16 or higher)
• npm, yarn, or pnpm
• Asgardeo account
• Claude Desktop

Quick Start

1. Clone the Repository

git clone https://github.com/ngsanthosh/typescript-mcp-auth-quickstart.git
cd typescript-mcp-auth-quickstart

2. Install Dependencies

npm install

3. Configure Asgardeo

1. Sign into your Asgardeo console
2. Navigate to Applications > New Application
3. Select Single Page Application and complete the wizard
   • Name: SecureMCPServer
   • Authorized Redirect URL: http://localhost:3000/oauth/callback
4. Save the following values from the application:
   • client-id (from Protocol tab)
   • Base URL (e.g., https://api.asgardeo.io/t/your-org)

4. Set Up Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Update .env with your Asgardeo configuration:

ASGARDEO_BASE_URL=https://api.asgardeo.io/t/your-org
PORT=3000

5. Build and Run

Development mode:

npm run dev

Production mode:

npm run build
npm start

The server will start on http://localhost:3000/mcp

6. Configure Claude Desktop

1. Open Claude Desktop
2. Go to Settings > Developer
3. Click Edit Config to open claude_desktop_config.json
4. Add the following configuration:

{
    "mcpServers": {
        "secure-whoami-server": {
            "command": "npx",
            "args": [
                "mcp-remote@latest",
                "http://localhost:3000/mcp",
                "--static-oauth-client-info",
                "{\"client_id\": \"<your-client-id>\"}",
                "--static-oauth-client-metadata",
                "{\"scope\": \"openid profile email\"}"
            ]
        }
    }
}

Replace <your-client-id> with the client ID from your Asgardeo application.

7. Test the Server

1. Restart Claude Desktop
2. You'll be redirected to Asgardeo for login
3. After authentication, ask Claude: "Who am I?"
4. The server will return your authenticated user profile information

Project Structure

.
├── src/
│   └── index.ts              # Main MCP server implementation
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Example environment variables
├── .gitignore                # Git ignore rules
├── README.md                 # This file
└── LICENSE                   # License

Key Features

• OAuth2 Authentication: Secure authentication via Asgardeo
• Type Safety: Full TypeScript support
• MCP Tools: Expose whoami tool that returns user profile
• Express Server: Built on Express.js for HTTP transport
• Authentication Middleware: Protect MCP endpoints with mcpAuthServer.protect()

Available Tools

whoami

Returns the authenticated user's profile information.

Input: None

Output:

{
  "profile": {
    "sub": "user-id",
    "email": "user@example.com",
    "given_name": "John",
    "family_name": "Doe",
    ...
  }
}

Environment Variables

Troubleshooting

"Not authenticated" Error

• Ensure you've created a test user in Asgardeo (guide)
• Verify your client ID is correct in Claude Desktop config
• Clear browser cache and try logging in again

Server Won't Start

• Check that port 3000 is not in use: lsof -i :3000
• Verify all environment variables are set in .env
• Ensure Node.js version is 16+

Module Not Found Errors

• Run npm install again
• Delete node_modules and package-lock.json, then reinstall

Learn More

• Asgardeo Documentation
• MCP Specification
• Asgardeo MCP Express SDK

License

MIT

Support

For issues and questions:

• Check the Asgardeo Documentation
• Visit Stack Overflow
• Open an issue in this repository