MCP Authentication Reference

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276

# MCP Authentication Reference

This document describes the authentication methods supported by mini-me's MCP client.

## Overview

MCP servers can require different authentication methods. Mini-me currently supports:

- **`none`**: No authentication (public servers)
- **`bearer`**: Bearer token authentication (HTTP Authorization header)
- **`api_key`**: API key authentication (custom header)

## Authentication Types

### Type: `none`

**Use case:** Public MCP servers that don't require authentication.

**Configuration:**
```yaml
servers:
  - name: wikipedia
    transport: http
    url: https://wikipedia-mcp.vercel.app/mcp
    auth:
      type: none
```

**Behavior:** No authentication headers are added to requests.

---

### Type: `bearer`

**Use case:** MCP servers that use Bearer token authentication (most common).

**Configuration:**
```yaml
servers:
  - name: github
    transport: http
    url: https://api.githubcopilot.com/mcp/
    auth:
      type: bearer
      tokenEnv: GITHUB_PERSONAL_ACCESS_TOKEN
```

**Required:** `tokenEnv` - Name of the environment variable containing the token.

**Behavior:** Adds `Authorization: Bearer {token}` header to all requests.

**HTTP Header:**
```
Authorization: Bearer ghp_your_token_here
```

**Supported servers:**
- GitHub MCP Server (`api.githubcopilot.com`)
- Context7 MCP Server (`mcp.context7.com`)
- Any server that accepts Bearer token authentication

---

### Type: `api_key`

**Use case:** MCP servers that use API key authentication with custom headers.

**Configuration:**
```yaml
servers:
  - name: duckduckgo
    transport: http
    url: https://mcp.hasdata.com/mcp
    auth:
      type: api_key
      apiKeyEnv: HASDATA_API_KEY
      apiKeyHeader: x-api-key
```

**Required:**
- `apiKeyEnv` - Name of the environment variable containing the API key
- `apiKeyHeader` - Name of the HTTP header to use

**Optional:** If `apiKeyHeader` is not specified, defaults to `Authorization`.

**Behavior:** Adds `{apiKeyHeader}: {api_key}` header to all requests.

**HTTP Header:**
```
X-API-Key: your_api_key_here
```

**Supported servers:**
- DuckDuckGo MCP Server via HasData

---

## Not Yet Supported

### OAuth 2.0

**Status:** Not yet implemented in mini-me.

**Use case:** MCP servers that require OAuth 2.0 authentication flow (browser-based login).

**Example server:** Some custom MCP servers that implement OAuth.

**Workaround:** Use a self-hosted MCP server that accepts Bearer tokens or API keys instead.

---

## Environment Variables

Authentication tokens and API keys are loaded from environment variables. This is a security best practice that prevents secrets from being committed to version control.

### Setting Environment Variables

**Linux/macOS:**
```bash
# Temporary (current session)
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"' >> ~/.bashrc
source ~/.bashrc

# Single command
GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here" mm --config your_config.yaml
```

**Windows (Command Prompt):**
```cmd
set GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
mm --config your_config.yaml
```

**Windows (PowerShell):**
```powershell
$env:GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"
mm --config your_config.yaml
```

### Best Practices

1. **Never hardcode secrets:** Always use environment variables or secret management systems
2. **Use `.env` files carefully:** If using `.env` files, add them to `.gitignore`
3. **Limit permissions:** Use tokens/API keys with minimum required permissions
4. **Rotate regularly:** Rotate tokens and API keys regularly
5. **Audit access:** Regularly review which services have access to your tokens

---

## Server-Specific Requirements

### GitHub MCP Server

**Endpoint:** `https://api.githubcopilot.com/mcp/`

**Authentication:** Bearer token (`bearer` type)

**Required scopes:**
- `read:user` - For user profile access (`get_me`)
- `repo` - For repository access (most tools)
- `read:org` - For organization access
- `user` - Basic user information

**Token type:** Classic Personal Access Token (PAT)

**Token generation:**
1. Go to [https://github.com/settings/tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Select required scopes
4. Generate token
5. Copy the token (it won't be shown again)

---

### Context7 MCP Server

**Endpoint:** `https://mcp.context7.com/mcp`

**Authentication:** Bearer token (`bearer` type)

**Token:** Context7 API key

**Token generation:**
1. Sign up at [https://context7.com](https://context7.com)
2. Get your API key from the dashboard
3. Set as `CONTEXT7_API_KEY` environment variable

---

### Wikipedia MCP Server

**Endpoint:** `https://wikipedia-mcp.vercel.app/mcp`

**Authentication:** None (`none` type)

**Token:** Not required

---

### HasData (DuckDuckGo) MCP Server

**Endpoint:** `https://mcp.hasdata.com/mcp?apis=duckduckgo`

**Authentication:** API key (`api_key` type)

**Token:** HasData API key

**Headers:**
- Header name: `x-api-key`
- Environment variable: `HASDATA_API_KEY`

---

## Troubleshooting

### "missing bearer token" or "missing API key" error

**Cause:** The required environment variable is not set or is empty.

**Solution:**
1. Verify the variable is set: `echo $VARIABLE_NAME`
2. Verify it's exported: `env | grep VARIABLE_NAME`
3. Check for typos in the variable name in your config

### Authentication fails but token works with curl

**Cause:** Different authentication requirements between REST API and MCP endpoint.

**Example:** GitHub REST API (`api.github.com`) vs GitHub MCP (`api.githubcopilot.com`)

**Solution:**
- Test directly with the MCP endpoint:
  ```bash
  curl -X POST https://api.githubcopilot.com/mcp/ \
    -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
  ```
- Ensure your token has the required scopes for the MCP server

### Server returns 403 Forbidden

**Cause:** Token lacks required permissions or server-specific requirements.

**Solution:**
- Check if the token has expired
- Verify the token has the correct scopes
- Some servers may require additional headers or parameters

### Server connection times out

**Solution:**
- Increase the `timeout` in your server configuration
- Check network connectivity to the MCP server endpoint
- Verify the server is online and accessible

---

## Security Considerations

1. **Token scope:** Only grant the minimum scopes required
2. **Token storage:** Use environment variables, not config files
3. **Token sharing:** Never share tokens or commit them to version control
4. **Token rotation:** Rotate tokens regularly, especially if compromised
5. **Network security:** Ensure connections to MCP servers use HTTPS

---

## See Also

- [MCP Configuration Reference](configuration.md)
- [Available MCP Tools](available-tools.md)
- [MCP Architecture](explanation/architecture.md)