# MCP Client Configuration — Okta OAuth for IDE Clients
Connect your IDE's MCP client to the self-hosted GitHub MCP Server through Okta OAuth (Authorization Code + PKCE).
## Prerequisites
1. **mcp-remote** — install globally:
```bash
npm install -g mcp-remote
```
2. **AWS Client VPN** — connected and able to reach the internal ALB
3. **Okta account** — you must be assigned to the Okta application
## MCP Client Configuration
### Kiro
Add to `~/.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"mcp-remote",
"https://<ALB_DNS>",
"--static-oauth-client-info",
"{\"client_id\":\"<OKTA_CLIENT_ID>\"}"
],
"env": {
"NODE_TLS_REJECT_UNAUTHORIZED": "0"
}
}
}
}
```
### Cursor
Add to `.cursor/mcp.json` or global settings:
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"mcp-remote",
"https://<ALB_DNS>",
"--static-oauth-client-info",
"{\"client_id\":\"<OKTA_CLIENT_ID>\"}"
],
"env": {
"NODE_TLS_REJECT_UNAUTHORIZED": "0"
}
}
}
}
```
### VS Code
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"github": {
"command": "npx",
"args": [
"mcp-remote",
"https://<ALB_DNS>",
"--static-oauth-client-info",
"{\"client_id\":\"<OKTA_CLIENT_ID>\"}"
],
"env": {
"NODE_TLS_REJECT_UNAUTHORIZED": "0"
}
}
}
}
```
> `NODE_TLS_REJECT_UNAUTHORIZED=0` is needed because the ALB uses a self-signed certificate.
## How It Works
1. `mcp-remote` fetches OAuth metadata from the server and discovers the Okta authorization endpoint
2. A browser opens to Okta's login page
3. You log in and consent to the requested scopes (`openid`, `profile`, `email`)
4. Okta redirects to `http://localhost:3334/oauth/callback` with an authorization code
5. `mcp-remote` exchanges the code for tokens via the server's token proxy (which strips unsupported parameters)
6. All subsequent MCP requests include the access token as a `Bearer` header
7. The JWT proxy in ECS validates the token against Okta's JWKS and proxies to Supergateway
8. `mcp-remote` auto-refreshes tokens when they expire
## Troubleshooting
### 401 Unauthorized
- Token may be expired. Restart the MCP server in your IDE to trigger a fresh OAuth flow.
- Verify you are assigned to the Okta application.
### Connection Refused / Timeout
- Confirm VPN is connected: `curl -sk https://<ALB_DNS>/healthz`
- Should return `ok`. If not, the service may be restarting — wait a minute and retry.
### CORS Errors
- Ensure your VPN connection is active. CORS errors usually mean the request isn't reaching the container.
### Token Expired / Refresh Issues
- `mcp-remote` handles token refresh automatically. If it keeps failing, restart the MCP connection in your IDE.
- Okta access tokens expire after 1 hour by default.
