# 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](https://nodejs.org/) (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](https://docs.vendia.com/platform/vendia-mcp-server/authentication).

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

Perfect for no-code integration platforms (e.g., [OpenAI Agent Builder](https://docs.vendia.com/platform/vendia-mcp-server/authentication#example-openai-agent-builder), Zapier, Make, n8n) that cannot perform OAuth flows.

#### Quick Setup

1. **Create API Credentials**: Follow the [API Authentication guide](https://docs.vendia.com/platform/operational/scalar-data/node-authentication#api-credentials) 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](https://docs.vendia.com/platform/vendia-mcp-server/authentication#service-credentials-via-headers-for-no-code-tools).

#### 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](https://docs.vendia.com/platform/operational/scalar-data/node-authentication#api-credentials) 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:

```javascript
// 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:

```javascript
// 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](https://docs.vendia.com/platform/operational/scalar-data/node-authentication).

#### 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](https://docs.vendia.com/platform/vendia-mcp-server/authentication) for authentication-specific issues
- Review the [API Authentication documentation](https://docs.vendia.com/platform/operational/scalar-data/node-authentication) for credential management

* * *