# 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](https://wso2.com/asgardeo/docs/get-started/create-asgardeo-account/)
- [Claude Desktop](https://claude.ai/download)

## Quick Start

### 1. Clone the Repository

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

### 2. Install Dependencies

```bash
npm install
```

### 3. Configure Asgardeo

1. Sign into your [Asgardeo console](https://console.asgardeo.io)
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:

```bash
cp .env.example .env
```

Update `.env` with your Asgardeo configuration:

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

### 5. Build and Run

**Development mode:**
```bash
npm run dev
```

**Production mode:**
```bash
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:

```json
{
    "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:**
```json
{
  "profile": {
    "sub": "user-id",
    "email": "user@example.com",
    "given_name": "John",
    "family_name": "Doe",
    ...
  }
}
```

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `ASGARDEO_BASE_URL` | Your Asgardeo organization base URL | `https://api.asgardeo.io/t/my-org` |
| `PORT` | Server port (default: 3000) | `3000` |

## Troubleshooting

### "Not authenticated" Error
- Ensure you've created a test user in Asgardeo ([guide](https://wso2.com/asgardeo/docs/guides/users/manage-users/#onboard-single-user))
- 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](https://wso2.com/asgardeo/docs/)
- [MCP Specification](https://modelcontextprotocol.io/specification/latest)
- [Asgardeo MCP Express SDK](https://www.npmjs.com/package/@asgardeo/mcp-express)

## License

MIT

## Support

For issues and questions:
- Check the [Asgardeo Documentation](https://wso2.com/asgardeo/docs/)
- Visit [Stack Overflow](https://stackoverflow.com/questions/tagged/wso2-asgardeo)
- Open an issue in this repository