# Authentication Methods

MCP Gateway supports multiple authentication methods to connect external MCP servers securely.

## Authentication Types

### OAuth 2.0 (Auto-configure)

Automatic OAuth registration is the recommended method for supported services.

**Available for:** Pre-configured services — Notion, Atlassian (Jira/Confluence), Sentry, Neon, Fireflies — and custom MCP servers that support OAuth 2.0

**Setup:**

1. Select **OAuth 2.0 (Auto-configure)**
2. Click **Add MCP Server**
3. You’ll be redirected back to the Vendia dashboard
4. Click **Connect** to begin the OAuth flow
5. A popup window will open to the third-party service’s login page
6. Sign in to the third-party account and grant the requested permissions
7. After authorization completes, select which tools to enable from the MCP server
8. Click **Enable X Tools** to complete the connection

### OAuth 2.0 (Use app credentials)

Use this when your organization has pre-registered an OAuth application.

**When to use:** Organization-managed OAuth apps, centralized control, custom configurations

**Setup:**

01. Obtain credentials from your administrator:
    - Client ID
    - Client Secret
    - Additional required credentials
02. Select **OAuth 2.0 (Use app credentials)**
03. Enter provided credentials
04. Click **Add MCP Server**
05. You’ll be redirected back to the Vendia dashboard
06. Click **Connect** to begin the OAuth flow
07. A popup window will open to the third-party service’s login page
08. Sign in to the third-party account and grant the requested permissions
09. After authorization completes, select which tools to enable from the MCP server
10. Click **Enable X Tools** to complete the connection

**Benefits:** Centralized management, consistent permissions, better audit trail, application-level access control.

### None / Headers

Use for MCP servers that don’t require OAuth or use API key authentication.

**When to use:** No authentication required, API key auth, custom headers, custom authentication schemes

**Setup:**

1. Select **None / Headers**
2. Click **Add Header** if authentication is needed
3. Enter header name (e.g., `Authorization`, `X-API-Key`)
4. Enter header value (e.g., `Bearer your-api-key`)
5. Add additional headers if needed
6. Click **Add MCP Server**
7. Select which tools to enable from the MCP server
8. Click **Enable X Tools** to complete the connection

**Common patterns:**

```
Bearer Token:

Header: Authorization

Value: Bearer your-access-token

API Key:

Header: X-API-Key

Value: your-api-key
```

## Custom Headers

Add custom headers for additional configuration or requirements.

**Use cases:** API keys, request routing, API versioning, custom metadata

**Adding headers:**

1. Locate **Headers (Optional)** section in configuration
2. Click **Add Header**
3. Enter header name (case-sensitive) and value
4. Repeat for additional headers

**Examples:**

```
API Version:

Header: X-API-Version

Value: 2.0

Request ID:

Header: X-Request-ID

Value: workspace-mcp-gateway
```

## Security Best Practices

**OAuth:**

- Review requested permissions carefully
- Grant minimum permissions needed
- Periodically audit connected applications
- Prefer auto-configure over app credentials

**API Keys:**

- Never commit keys to version control
- Rotate keys regularly
- Use keys with minimal permissions
- Monitor usage for anomalies

**General:**

- Connect only trusted MCP servers
- Verify HTTPS connections
- Audit and remove unused connections
- Document why servers are connected

## Troubleshooting Authentication

**OAuth Authorization Failed:**

- Enable popups for Vendia’s domain
- Verify authorization permissions
- Check external service accessibility
- Contact administrator if using app credentials

**API Key Not Working:**

- Verify key is correct and not expired
- Check header names (case-sensitive)
- Ensure key has necessary permissions
- Test key directly with external service

**Custom Headers Not Applied:**

- Verify header names match exactly
- Check for typos and extra spaces
- Review service’s header requirements
- Test with curl or Postman first