Advanced Connection Methods

This guide covers advanced connection methods for Vendia MCP Gateway beyond the standard direct remote MCP connection. These methods are useful for specific use cases such as legacy clients, no-code tools, and custom applications requiring programmatic control.

Option 1: Local Proxy Connection (Legacy)

For older MCP clients that don’t support remote connections, you can use a local proxy. This requires Node.js and npm installed on your machine.

Prerequisites

Node.js and npm: Install Node.js (version 22 LTS or later) from the official website or via command line:

macOS/Linux:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

Windows:

winget install OpenJS.NodeJS.LTS

Configuration Steps

1. Get Your MCP Server URL:
   • Free & Pro Tier: Available in your Vendia console
   • Enterprise Tier: Found in Project Settings → Resources in your Vendia project dashboard
2. Edit Your Client’s Configuration File: Update your client’s configuration to use the npx proxy:

{
    "mcpServers": {
      "vendia": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "YOUR_MCP_SERVER_URL"]
      }
    }
}

Note: Replace "YOUR_MCP_SERVER_URL" with your actual MCP Server URL.

3. Restart Your MCP Client: Restart the client and authenticate when prompted.

When to Use Local Proxy

• Your MCP client doesn’t support remote connections
• You need to route MCP traffic through a local process
• You’re testing or debugging MCP connections locally

Option 2: Programmatic Access for AI Applications - Pro & Enterprise Tiers

For building AI applications that need programmatic access to the Vendia MCP Gateway, you have two authentication options:

• Service Credentials via Headers - Simplified authentication for no-code/low-code tools
• Programmatic Token Exchange - Full control for custom applications

For detailed information about all authentication methods, including security considerations and when to use each approach, see the Authentication Methods guide.

Option 2A: Service Credentials via Headers (No-Code Tools) - Pro & Enterprise Tiers

Perfect for no-code integration platforms (e.g., OpenAI Agent Builder, Zapier, Make, n8n) that cannot perform OAuth flows.

Quick Setup

1. Create API Credentials: Follow the API Authentication guide to create API credentials.

2. Configure Headers: Configure your tool to send these headers with each request:

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

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

3. Automatic Token Exchange: The MCP server automatically exchanges credentials for tokens.

Platform-Specific Guides

For platform-specific setup instructions and security considerations, see the Service Credentials documentation.

When to Use Service Credentials

Option 2B: Programmatic Token Exchange (Custom Applications) - Pro & Enterprise Tiers

For custom applications requiring full control over authentication and token management.

Step 1: Create API Credentials

1. Follow the API Authentication guide to create API credentials
2. Note your client_id and client_secret

Step 2: Exchange Credentials for Access Token

Your application needs to exchange the credentials for a JWT token:

// Example: Exchange credentials for access token

const response = await fetch("https://auth.share.vendia.com/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "YOUR_CLIENT_ID", // Replace with your actual client ID
    client_secret: "YOUR_CLIENT_SECRET", // Replace with your actual client secret
  }),
});

const { access_token } = await response.json();

Step 3: Configure AI SDK with Bearer Token - Pro & Enterprise Tiers

Configure your AI SDK to connect to the MCP server with the authorization header:

// Example configuration using the OpenAI SDK

const resp = await client.responses.create({
  model: "gpt-4.1",
  tools: [
    { 
      type: "mcp",
      server_label: "Vendia",
      require_approval: "never",
      server_url: "YOUR_MCP_SERVER_URL",
      headers: {
        Authorization: `Bearer ${vendiaAccessToken.access_token}`,
      },
    },
  ],
  input: "Tell me about my tables in Vendia",
});

Additional Resources

For complete examples and token refresh logic, see the API Authentication documentation.

When to Use Programmatic Access

Use programmatic token exchange when:

• Building custom AI applications
• You need full control over token management
• You want to implement custom authentication logic
• Your application requires token refresh and lifecycle management

Troubleshooting

Local Proxy Issues

Proxy Not Starting:

• Verify Node.js (v22 LTS or later) is installed: node --version
• Check npm is available: npm --version
• Ensure the mcp-remote package can be accessed via npx

Connection Failures:

• Verify your MCP Server URL is correct
• Check that you have network access to Vendia servers
• Review terminal output for specific error messages

Programmatic Access Issues

Authentication Failures:

• Verify your API credentials are correct and active
• Ensure credentials have proper DATA_READ permissions (Enterprise Tier)
• Check that you’re using the correct authentication endpoint

Token Exchange Errors:

• Confirm the token exchange request format matches the examples
• Verify the Content-Type header is set to application/x-www-form-urlencoded
• Check that grant_type is set to client_credentials

Bearer Token Issues:

• Ensure the Authorization header format is correct: Bearer <token>
• Check token expiration and implement refresh logic if needed
• Verify the token has the necessary permissions

For more detailed troubleshooting:

• See the Authentication Methods guide for authentication-specific issues
• Review the API Authentication documentation for credential management