Skip to content

Commit 291fb10

Browse files
zereightzereight
committed
Squashed commit of the following:
commit cce5d07 Author: zereight <[email protected]> Date: Fri Aug 15 18:31:25 2025 +0900 fix: update version to 2.0.0 in package.json and package-lock.json commit 841e3ab Author: a <[email protected]> Date: Fri Aug 15 04:27:49 2025 -0500 User based authentication methods (#130) * noot * noot * wip * wip * wip * noot * noot * noot * noot * noot * add some ai documentation * multiple transports * argon2 fix * npm i * change default token expiry * noot * fix build * remove unused env var * add some logging * add GITLAB_API_URL to the examples * argon2 warning * Fix list of tools * feat: Add NPM publish workflow for automated package publishing (#208) * single logger --------- Co-authored-by: Hunter Wittenborn <[email protected]> Co-authored-by: iwakitakuma <[email protected]> Co-authored-by: zereight <[email protected]> commit d5a652d Author: zereight <[email protected]> Date: Wed Aug 13 18:32:11 2025 +0900 fix: update version to 2.0.0-beta.0 and rename deploy scripts commit f25e149 Author: zereight <[email protected]> Date: Wed Aug 13 18:26:11 2025 +0900 fix: rename deploy:canary script to deploy:beta commit cf1e6d3 Author: zereight <[email protected]> Date: Wed Aug 13 18:22:15 2025 +0900 fix: update version to 2.0.0 and modify deploy:canary script commit 1751d1d Author: zereight <[email protected]> Date: Wed Aug 13 18:10:45 2025 +0900 feat: update version to 2.0.0-canary.0
1 parent d254e5b commit 291fb10

16 files changed

+7074
-5366
lines changed

‎docs/oauth2_proxy.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# GitLab MCP OAuth2 Proxy Configuration
2+
3+
This guide explains how to configure the GitLab MCP server to use OAuth2 proxy authentication, allowing users to authenticate with GitLab OAuth2 applications instead of using personal access tokens.
4+
5+
## Overview
6+
7+
The OAuth2 proxy mode enables dynamic client registration and token management, providing a more secure and flexible authentication method compared to static personal access tokens.
8+
9+
**Note:** OAuth2 proxy mode is only available when using SSE or STREAMABLE_HTTP transport modes. It is not supported with STDIO transport.
10+
11+
## Required Environment Variables
12+
13+
To enable OAuth2 proxy mode, you must set the following environment variables:
14+
15+
### Core OAuth2 Configuration
16+
17+
```bash
18+
# GitLab OAuth2 Application Credentials
19+
GITLAB_OAUTH2_CLIENT_ID=your_gitlab_app_id
20+
GITLAB_OAUTH2_CLIENT_SECRET=your_gitlab_app_secret
21+
22+
# GitLab OAuth2 Endpoints
23+
GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.com/oauth/authorize
24+
GITLAB_OAUTH2_TOKEN_URL=https://gitlab.com/oauth/token
25+
GITLAB_OAUTH2_ISSUER_URL=https://gitlab.com
26+
GITLAB_OAUTH2_BASE_URL=http://localhost:3000 # Your MCP server URL
27+
28+
# OAuth2 Redirect Configuration
29+
GITLAB_OAUTH2_REDIRECT_URL=http://localhost:3000/callback
30+
```
31+
32+
### Optional Configuration
33+
34+
```bash
35+
# Token Revocation Endpoint (optional)
36+
GITLAB_OAUTH2_REVOCATION_URL=https://gitlab.com/oauth/revoke
37+
38+
# Database Path (defaults to in-memory if not set)
39+
GITLAB_OAUTH2_DB_PATH=/path/to/oauth.db
40+
```
41+
42+
## Setting Up a GitLab OAuth2 Application
43+
44+
1. Go to your GitLab instance (e.g., https://gitlab.com)
45+
2. Navigate to **User Settings** → **Applications**
46+
3. Create a new application with:
47+
- **Name**: Your MCP Server (or any descriptive name)
48+
- **Redirect URI**: Must match `GITLAB_OAUTH2_REDIRECT_URL` exactly (e.g., `http://localhost:3000/callback`)
49+
- **Scopes**: Select the following:
50+
- `api` - Access the authenticated user's API
51+
- `openid` - Authenticate using OpenID Connect
52+
- `profile` - Read user's profile data
53+
- `email` - Read user's email address
54+
55+
4. After creation, GitLab will provide:
56+
- **Application ID**: Use this for `GITLAB_OAUTH2_CLIENT_ID`
57+
- **Secret**: Use this for `GITLAB_OAUTH2_CLIENT_SECRET`
58+
59+
## Configuration Examples
60+
61+
### Development Setup (localhost)
62+
63+
```bash
64+
# .env file
65+
GITLAB_API_URL=https://gitlab.com
66+
67+
GITLAB_OAUTH2_CLIENT_ID=your_app_id_here
68+
GITLAB_OAUTH2_CLIENT_SECRET=your_app_secret_here
69+
GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.com/oauth/authorize
70+
GITLAB_OAUTH2_TOKEN_URL=https://gitlab.com/oauth/token
71+
GITLAB_OAUTH2_ISSUER_URL=https://gitlab.com
72+
GITLAB_OAUTH2_BASE_URL=http://localhost:3000
73+
GITLAB_OAUTH2_REDIRECT_URL=http://localhost:3000/callback
74+
```
75+
76+
### Production Setup
77+
78+
```bash
79+
# .env file
80+
GITLAB_API_URL=https://gitlab.company.com
81+
82+
GITLAB_OAUTH2_CLIENT_ID=your_app_id_here
83+
GITLAB_OAUTH2_CLIENT_SECRET=your_app_secret_here
84+
GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.company.com/oauth/authorize
85+
GITLAB_OAUTH2_TOKEN_URL=https://gitlab.company.com/oauth/token
86+
GITLAB_OAUTH2_ISSUER_URL=https://gitlab.company.com
87+
GITLAB_OAUTH2_BASE_URL=https://mcp.company.com
88+
GITLAB_OAUTH2_REDIRECT_URL=https://mcp.company.com/callback
89+
GITLAB_OAUTH2_DB_PATH=/var/lib/gitlab-mcp/oauth.db
90+
```
91+
92+
## Database Storage
93+
94+
By default, the OAuth2 proxy uses an in-memory SQLite database. For production use, specify a persistent database path:
95+
96+
```bash
97+
GITLAB_OAUTH2_DB_PATH=/path/to/persistent/oauth.db
98+
```
99+
100+
The database stores:
101+
- OAuth client registrations
102+
- State mappings for OAuth flow
103+
- Access token hashes (using Argon2 for security)
104+
105+
## Security Considerations
106+
107+
1. **Client Secrets**: Never commit `GITLAB_OAUTH2_CLIENT_SECRET` to version control
108+
2. **HTTPS**: Always use HTTPS for production deployments
109+
3. **Token Storage**: Access tokens are hashed using Argon2 before storage
110+
4. **Token Expiry**: Tokens expire after 1 hour by default
111+
5. **State Expiry**: OAuth state parameters expire after 15 minutes
112+
113+
## Troubleshooting
114+
115+
### Common Issues
116+
117+
1. **"Protected resource URL mismatch"**
118+
- Ensure `GITLAB_OAUTH2_BASE_URL` matches your server's actual URL
119+
- Check that the redirect URI in GitLab matches `GITLAB_OAUTH2_REDIRECT_URL`
120+
121+
2. **"Invalid redirect URI"**
122+
- The redirect URI must match exactly (including protocol and port)
123+
- No trailing slashes unless specified in GitLab
124+
125+
3. **"Invalid scope"**
126+
- Ensure your GitLab OAuth app has the required scopes enabled
127+
- The MCP server requests: `api`, `openid`, `profile`, `email`
128+
129+
130+
## Starting the Server
131+
132+
OAuth2 proxy mode requires SSE or STREAMABLE_HTTP transport.
133+
134+
The server will log:
135+
```
136+
Configuring GitLab OAuth2 proxy authentication
137+
```
138+
139+
**Note:** STDIO transport mode does not support OAuth2 proxy authentication.
140+
141+
## Client Configuration
142+
143+
MCP clients connecting to an OAuth2-enabled server should use the OAuth2 flow instead of providing a GitLab token directly. The server will handle dynamic client registration and token management automatically.
144+
145+
## Note
146+
147+
OAuth2 proxy support is currently in beta. While functional, it may have limitations compared to personal access token authentication. Please report any issues to the project's issue tracker.

‎docs/passthrough_mode.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# GitLab MCP Passthrough Authentication Mode
2+
3+
This guide explains how to configure the GitLab MCP server to use passthrough authentication mode, where users provide their own GitLab Personal Access Token (PAT) with each request.
4+
5+
## Overview
6+
7+
Passthrough mode allows multiple users to use the same MCP server instance with their own GitLab credentials. Each user provides their GitLab Personal Access Token via the `Gitlab-Token` header, and the server uses that token for all GitLab API requests.
8+
9+
This mode is ideal for:
10+
- Multi-user environments
11+
- Scenarios where you don't want to store tokens on the server
12+
- Testing with different access levels
13+
14+
## Configuration
15+
16+
To enable passthrough mode, set the following environment variable:
17+
18+
```bash
19+
GITLAB_PAT_PASSTHROUGH=true
20+
```
21+
22+
**Important:** When using passthrough mode, do not set:
23+
- `GITLAB_PERSONAL_ACCESS_TOKEN`
24+
- `GITLAB_OAUTH2_CLIENT_ID` (or any OAuth2 configuration)
25+
26+
## How It Works
27+
28+
1. The MCP server starts without any pre-configured authentication
29+
2. Each client request must include a `Gitlab-Token` header with a valid GitLab PAT
30+
3. The server uses the provided token for that specific request
31+
4. No tokens are stored or cached by the server
32+
33+
## Client Configuration
34+
35+
### Using with MCP Client
36+
37+
When connecting to a passthrough-enabled server, clients must provide the GitLab token with each request:
38+
39+
```typescript
40+
// Example client configuration
41+
const client = new MCPClient({
42+
url: 'http://localhost:3000',
43+
headers: {
44+
'Gitlab-Token': 'your-gitlab-personal-access-token'
45+
}
46+
});
47+
```
48+
49+
### Using with cURL
50+
51+
```bash
52+
curl -H "Gitlab-Token: your-gitlab-personal-access-token" \
53+
http://localhost:3000/your-endpoint
54+
```
55+
56+
### Using with HTTP Libraries
57+
58+
```javascript
59+
// Node.js with fetch
60+
const response = await fetch('http://localhost:3000/your-endpoint', {
61+
headers: {
62+
'Gitlab-Token': 'your-gitlab-personal-access-token'
63+
}
64+
});
65+
```
66+
67+
## Creating a GitLab Personal Access Token
68+
69+
1. Go to GitLab (e.g., https://gitlab.com)
70+
2. Navigate to **User Settings** → **Access Tokens**
71+
3. Create a new token with:
72+
- **Token name**: Descriptive name (e.g., "MCP Client")
73+
- **Expiration date**: Set as needed
74+
- **Scopes**: Select based on your needs:
75+
- `api` - Full API access (recommended)
76+
- `read_api` - Read-only API access
77+
- `read_repository` - Read repository content
78+
- `write_repository` - Write repository content
79+
80+
4. Copy the generated token and use it in the `Gitlab-Token` header
81+
82+
## Security Considerations
83+
84+
1. **Token Transmission**: Tokens are sent with every request
85+
- Always use HTTPS in production to encrypt tokens in transit
86+
- Never log or store tokens on the client side in plain text
87+
88+
2. **No Server Storage**: The server does not store any tokens
89+
- Each request is authenticated independently
90+
- No session management or token caching
91+
92+
3. **Token Scope**: Users control their own access levels
93+
- Each user's token determines what they can access
94+
- Server has no control over permissions
95+
96+
## Error Handling
97+
98+
### Missing Token
99+
If a request is made without the `Gitlab-Token` header:
100+
```
101+
Status: 401 Unauthorized
102+
Body: "Please set a Gitlab-Token header in your request"
103+
```
104+
105+
### Invalid Token Format
106+
If the token is not a string or is sent multiple times:
107+
```
108+
Status: 401 Unauthorized
109+
Body: "Gitlab-Token must only be set once"
110+
```
111+
112+
### Invalid GitLab Token
113+
If GitLab rejects the token:
114+
```
115+
Status: 401 Unauthorized
116+
Body: GitLab API error message
117+
```
118+
119+
## Starting the Server
120+
121+
Start the server with passthrough mode enabled:
122+
123+
```bash
124+
GITLAB_PAT_PASSTHROUGH=true npm dev
125+
```
126+
127+
The server will log:
128+
```
129+
Configuring GitLab PAT passthrough authentication. Users must set the Gitlab-Token header in their requests
130+
```
131+
132+
## Comparison with Other Modes
133+
134+
| Feature | Passthrough | Static PAT | OAuth2 Proxy |
135+
|---------|------------|------------|--------------|
136+
| Multi-user support | ✅ Yes | ❌ No | ✅ Yes |
137+
| Token storage | ❌ None | ✅ Server | ✅ Database |
138+
| Setup complexity | Low | Low | High |
139+
| Transport support | All | All | SSE/HTTP only |
140+
| User token control | ✅ Full | ❌ None | ⚠️ Limited |
141+
142+
## Example: Full Request Flow
143+
144+
1. User creates a GitLab PAT with necessary scopes
145+
2. User configures their MCP client with the token:
146+
```javascript
147+
const client = new MCPClient({
148+
url: 'http://localhost:3000',
149+
headers: {
150+
'Gitlab-Token': 'glpat-xxxxxxxxxxxxxxxxxxxx'
151+
}
152+
});
153+
```
154+
3. Client makes a request to list projects
155+
4. MCP server receives request with token header
156+
5. Server forwards the token to GitLab API
157+
6. GitLab validates token and returns data
158+
7. Server returns data to client
159+
160+
## Troubleshooting
161+
162+
### Token Not Working
163+
- Verify the token has not expired
164+
- Check that the token has the required scopes
165+
- Ensure the token is from the correct GitLab instance
166+
- Try the token directly with GitLab API to verify it works
167+
168+
### Multiple Users Issues
169+
- Each user must use their own token
170+
- Tokens should not be shared between users
171+
- Consider OAuth2 mode for better multi-user management
172+
173+
## Best Practices
174+
175+
1. **Token Rotation**: Regularly rotate PATs for security
176+
2. **Minimal Scopes**: Use tokens with only necessary scopes
177+
3. **HTTPS Only**: Always use HTTPS in production
178+
4. **Client Security**: Store tokens securely on client side
179+
5. **Monitoring**: Log request counts but never log tokens
180+
181+
## Note
182+
183+
Passthrough mode is ideal for development and multi-user scenarios where each user manages their own credentials. For production deployments with many users, consider using OAuth2 proxy mode for better token management and security.

0 commit comments

Comments
 (0)