MCP Server Authentication Methods

Vendia MCP Server 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 Options

OAuth Flow (Recommended for Interactive Applications)

The standard authentication method for AI applications like Claude Desktop, Claude Web, 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 Server
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)
• Web-based AI applications (e.g., Claude Web, Mistral AI: Le Chat, ChatGPT, OpenAI Platform)
• Applications where users can complete an interactive login

Setup: See the Getting Started Guide 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

Security Note

Service credentials provide a simpler authentication flow but require embedding credentials in your application configuration. Use this method only when your integration tool cannot support OAuth flows. For maximum security, prefer OAuth authentication when possible.

Step 1: Create API Credentials

1. Follow the API Authentication guide 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.

Credential Security

Store your client ID and client secret securely. These credentials provide access to your Vendia data according to their assigned permissions. Never commit credentials to version control or expose them in client-side code.

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:

// 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
  }),
});

# 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 Getting Started - Option 3 for detailed implementation.

---

Authentication Method Comparison

Feature	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

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 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 for your workspace
• Review audit logs in Receipts
• Confirm data access policies are correctly configured

Need Help?

If you encounter authentication issues or have questions:

Free Tier Support

• Review the MCP Free Tier FAQ for common questions
• Submit questions via our contact form

Enterprise Tier Support

• Check the MCP Server FAQ for common questions
• Review Role-Based Access Control documentation
• Contact Vendia Support 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!