# MCP Server Authentication Methods

Vendia MCP Gateway supports multiple authentication methods to accommodate different types of AI applications and integration tools. Choose the method that best fits your use case and technical requirements.

## Authentication Method Comparison

| Method                       | OAuth Flow    | Service Credentials  | Programmatic Token Exchange |
|------------------------------|---------------|-----------------------|------------------------------|
| **Setup Complexity**         | Simple        | Simple                | Moderate                     |
| **User Interaction**         | Required      | Not required          | Not required                 |
| **Best For**                 | Interactive AI apps | No-code tools        | Custom applications           |
| **Token Management**         | Automatic     | Automatic             | Manual                       |
| **Security Level**           | Highest       | Medium                | High                         |
| **Credential Storage**       | Secure token storage | Headers (tool-dependent) | Application managed           |

* * *

## Authentication Methods

### OAuth Flow (Recommended for Interactive Applications)

The standard authentication method for AI applications like Claude and other interactive tools. This method is recommended for applications where users can complete an interactive login flow.

**How it works:**

1. Your AI application initiates authentication with Vendia MCP Gateway
2. You’re redirected to authenticate in your browser
3. After successful login, your application receives an access token
4. The application uses this token for subsequent MCP requests

**Best for:**
- Desktop AI applications (e.g., Claude Desktop, ChatGPT Desktop)
- Web-based AI applications (e.g., Claude Web, Mistral AI: Le Chat, ChatGPT Web, OpenAI Platform)
- Applications where users can complete an interactive login

**Setup:** See the [Getting Started Guide](https://docs.vendia.com/platform/vendia-mcp-server/getting-started) for detailed OAuth configuration instructions.

### Service Credentials via Headers (For No-Code Tools)

A simplified authentication method designed for no-code and low-code integration tools that cannot perform OAuth flows or programmatic token exchange. Pass your API credentials directly in request headers, and the MCP server handles token exchange automatically.

**How it works:**

1. Create API credentials in Vendia (client ID and client secret)
2. Configure your no-code tool to send credentials in custom headers
3. The MCP server exchanges credentials for a JWT token automatically
4. Your requests proceed with proper authentication

**Best for:**
- No-code integration platforms (e.g., OpenAI Agent Builder, Zapier, Make, n8n)
- Low-code tools without OAuth support
- Custom integrations with simplified authentication requirements

**When NOT to use:**
- Standard applications that can implement OAuth flows (use OAuth instead)
- High-security environments requiring user-level authentication
- Applications where you want to avoid embedding credentials

#### Step 1: Create API Credentials

1. Follow the [API Authentication guide](https://docs.vendia.com/platform/operational/scalar-data/node-authentication#api-credentials) to create API credentials for your **project**
2. Save your `client_id` and `client_secret` securely
3. Note the permissions associated with your credentials (based on the assigned role). For MCP access, your credentials must include the `DATA_READ` permission for the specific **project** and **workspace** that your MCP server is attached to.

#### Step 2: Configure Request Headers

Configure your no-code tool or application to include the following custom headers with each MCP request:

```
X-Vendia-Client-Id: your-client-id-here

X-Vendia-Client-Secret: your-client-secret-here
```

**Configuration Examples:**

Most no-code and low-code platforms support adding custom headers to HTTP requests. The exact steps vary by platform, but generally you’ll look for settings such as:
- **Headers**, **Custom Headers**, or **Header Parameters** section
- Ability to add key-value pairs for HTTP headers
- HTTP request or webhook configuration options

##### Example: OpenAI Agent Builder

When configuring a custom action or connector in OpenAI Agent Builder:

1. In the **Headers** section, add two custom headers:

- Header name: `X-Vendia-Client-Id`
   - Header value: `your-client-id-here`
   - Header name: `X-Vendia-Client-Secret`
   - Header value: `your-client-secret-here`

##### Other Platforms

For other no-code/low-code platforms (e.g., Zapier, Make, n8n), add the same two headers (`X-Vendia-Client-Id` and `X-Vendia-Client-Secret`) using your platform’s header configuration interface. Consult your platform’s documentation for specific instructions on adding custom headers to HTTP requests.

**Custom Applications:**

If you’re building a custom integration, include the headers in your HTTP requests:

```javascript
// Example using fetch API

const response = await fetch("YOUR_MCP_SERVER_URL", {
    
    method: "POST",
    
    headers: {
        "Content-Type": "application/json",
        
        "X-Vendia-Client-Id": "your-client-id-here",
        
        "X-Vendia-Client-Secret": "your-client-secret-here",
    },
    
    body: JSON.stringify({
        // Your MCP request payload
    }),
});
```

```python
# Example using Python requests

import requests

response = requests.post(
    
    'YOUR_MCP_SERVER_URL',
    
    headers={
        'Content-Type': 'application/json',
        
        'X-Vendia-Client-Id': 'your-client-id-here',
        
        'X-Vendia-Client-Secret': 'your-client-secret-here'
    },
    
    json={
        # Your MCP request payload
    }
)
```

#### Step 3: Verify Authentication

Test your configuration by making a simple MCP request:

1. Use your no-code tool to send a basic request to the MCP server
2. Verify you receive a successful response
3. Check that you can access expected data based on your credential permissions

**Common Test Operations:**
- List available MCP tools
- Query your **project** schema
- Run a simple operational query
- Execute a basic analytical query

If authentication fails, verify:
- Credentials are correct and active
- Headers are properly formatted
- Network allows connections to Vendia servers
- API credentials have appropriate permissions

### Programmatic Token Exchange (For Custom Applications)

For building custom AI applications that need full control over authentication, you can implement the OAuth2 client credentials flow directly in your code.

**How it works:**

1. Create API credentials in Vendia
2. Your application exchanges credentials for a JWT access token
3. Use the token in the `Authorization: Bearer <token>` header
4. Implement token refresh logic when tokens expire

**Best for:**
- Custom AI applications with sophisticated authentication requirements
- Applications needing fine-grained token management
- Integrations requiring custom token caching or rotation strategies

**Setup:** See [Advanced Connection Methods - Programmatic Access](https://docs.vendia.com/platform/vendia-mcp-server/advanced-connection-methods#option-2b-programmatic-token-exchange-custom-applications) for detailed implementation.

## Security Best Practices

Follow these best practices to keep your Vendia credentials and data secure:
- Store credentials in environment variables or a secure secrets manager. Never commit credentials to version control.
- Rotate credentials regularly. Remove unused API credentials from your **project** and create new ones as needed.
- Grant only the permissions required. Create API credentials with the minimum access needed for your **project** or **workspace**.
- Use dedicated credentials for each integration or tool.
- Monitor usage and audit permissions. Review [Receipts](https://docs.vendia.com/platform/receipts) to track API credential activity and audit which credentials have access to your **project** data.
- Use HTTPS for all connections. Never send credentials over unencrypted channels.
- Restrict network access to your **workspace** using IP allowlisting or firewall rules when possible.
- Store tokens and secrets securely. Clear tokens on logout.
- Respect token expiration and implement refresh logic in your application.
- For no-code tools, encrypt stored credentials and use OAuth if your tool supports it.

## Troubleshooting Authentication Issues

### OAuth Flow Issues

**Problem:** Authentication redirect doesn’t work

**Solutions:**
- Check popup blockers aren’t preventing the authentication window
- Verify your MCP Server URL is correct
- Ensure you have an active Vendia account with appropriate permissions

**Problem:** Token expires frequently

**Solutions:**
- This is expected behavior for security
- Modern AI clients handle token refresh automatically
- For custom apps, implement token refresh logic

### Service Credentials Issues

**Problem:** Authentication fails with 401 Unauthorized

**Solutions:**
- Verify `X-Vendia-Client-Id` and `X-Vendia-Client-Secret` headers are correctly set
- Check credentials are active (not expired or deleted)
- Ensure credentials have appropriate role permissions
- Verify header names are exactly as specified (case-sensitive)

**Problem:** Headers not being sent

**Solutions:**
- Check your no-code tool’s header configuration
- Verify the tool supports custom headers
- Test with a simple HTTP client (like Postman) first
- Review tool-specific documentation for header configuration

**Problem:** Credentials work in testing but fail in production

**Solutions:**
- Ensure production environment has correct credentials configured
- Verify environment variables are properly set
- Check for credential encoding issues
- Review network/firewall restrictions

### Programmatic Token Exchange Issues

**Problem:** Token exchange fails

**Solutions:**
- Verify OAuth endpoint URL is correct (`https://auth.share.vendia.com/token`)
- Check `grant_type` is set to `client_credentials`
- Ensure credentials are properly URL-encoded
- Review request Content-Type header

**Problem:** Token refresh logic not working

**Solutions:**
- Implement proper token expiration checking
- Cache tokens with 80% of their lifetime (e.g., 2880s for 3600s tokens)
- Handle token refresh failures gracefully
- Log token lifecycle events for debugging

### General Authentication Issues

**Problem:** Intermittent authentication failures

**Solutions:**
- Check network stability and latency
- Verify Vendia service status
- Review rate limiting policies
- Implement retry logic with exponential backoff

**Problem:** Permission denied after successful authentication

**Solutions:**
- Verify the authenticated role has necessary permissions
- Check [RBAC configuration](https://docs.vendia.com/platform/operational/secure-data-sharing/rbac) for your **workspace**
- Review audit logs in [Receipts](https://docs.vendia.com/platform/receipts)
- Confirm data access policies are correctly configured

## Need Help?

If you encounter authentication issues or have questions:

### Free Tier Support

- Review the [MCP Gateway FAQ](https://docs.vendia.com/platform/free-tier-faq) for common questions
- Submit questions via our [contact form](https://www.vendia.com/contact-us/)

### Pro Tier Support

- Submit questions via your dedicated slack channel

### Enterprise Tier Support

- Check the [MCP Server FAQ](https://docs.vendia.com/platform/vendia-mcp-server/faq) for common questions
- Review [Role-Based Access Control](https://docs.vendia.com/platform/operational/secure-data-sharing/rbac) documentation
- Contact [Vendia Support](mailto:support@vendia.com) for technical assistance
- Reach out to your account team for enterprise support

The Vendia team is here to help you securely connect your AI applications to your data!