MCP Authentication

Authentication and security for Model Context Protocol

Detailed guide for authenticating with the Appizer Model Context Protocol (MCP) server.

API Key Management

MCP uses dedicated API keys that are separate from your regular Appizer API keys.

Creating an MCP API Key

  1. Navigate to your organization settings
  2. Go to the "MCP" section
  3. Click "Generate New MCP API Key"
  4. Store the key securely (it will only be shown once)

Using the API Key

Include the MCP API key in the X-MCP-API-Key header:

X-MCP-API-Key: YOUR_MCP_API_KEY

Validating Authentication

Test your MCP API key by calling the auth endpoint:

curl -X GET https://api.appizer.com/mcp/auth \
  -H "X-MCP-API-Key: YOUR_MCP_API_KEY"

Successful Response:

{
  "authenticated": true,
  "organization": {
    "id": "org_123",
    "name": "Acme Corp",
    "description": "Enterprise solutions",
    "timezone": "America/New_York"
  },
  "permissions": ["read", "write"],
  "protocol_version": "1.0"
}

Failed Authentication:

{
  "authenticated": false,
  "error": "Invalid API key"
}

Permissions

MCP API keys have the following permission levels:

  • read - Access to view data (events, users, audiences)
  • write - Ability to create and modify resources
  • admin - Full access including key management

Environment Configuration

Store your MCP API key securely using environment variables:

.env File

# Development environment
APPIZER_MCP_API_KEY=your_dev_mcp_key_here
APPIZER_MCP_BASE_URL=https://api.appizer.com/mcp
APPIZER_ORG_ID=your_org_id_here

# For production, use a different key with appropriate permissions
# APPIZER_MCP_API_KEY_PROD=your_prod_mcp_key_here

# For AI integrations
OPENAI_API_KEY=your_openai_key_here

Loading in Code

JavaScript/Node.js:

require('dotenv').config();

const mcpApiKey = process.env.APPIZER_MCP_API_KEY;
const mcpBaseUrl = process.env.APPIZER_MCP_BASE_URL;

Python:

import os
from dotenv import load_dotenv

load_dotenv()

mcp_api_key = os.getenv('APPIZER_MCP_API_KEY')
mcp_base_url = os.getenv('APPIZER_MCP_BASE_URL')

Security Best Practices

Key Rotation

Rotate MCP API keys regularly:

  1. Generate a new MCP API key
  2. Update your applications with the new key
  3. Test that the new key works
  4. Revoke the old key

Access Logging

Monitor all MCP API access:

const winston = require('winston');
const axios = require('axios');

// Configure logger
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  defaultMeta: { service: 'mcp-client' },
  transports: [
    new winston.transports.File({ filename: 'mcp-access.log' })
  ]
});

// Create axios instance with interceptors
const mcpClient = axios.create({
  baseURL: process.env.APPIZER_MCP_BASE_URL,
  headers: { 'X-MCP-API-Key': process.env.APPIZER_MCP_API_KEY }
});

// Log all requests
mcpClient.interceptors.request.use(request => {
  logger.info('MCP API Request', {
    method: request.method,
    url: request.url,
    params: request.params
  });
  return request;
});

// Log all responses
mcpClient.interceptors.response.use(
  response => {
    logger.info('MCP API Response', {
      status: response.status,
      data: response.data ? 'Data received' : 'No data'
    });
    return response;
  },
  error => {
    logger.error('MCP API Error', {
      status: error.response?.status,
      message: error.message
    });
    return Promise.reject(error);
  }
);

Rate Limiting

Implement client-side rate limiting to avoid overwhelming the API:

class RateLimitedMCPClient {
  constructor(apiKey, maxRequestsPerMinute = 100) {
    this.apiKey = apiKey;
    this.maxRequests = maxRequestsPerMinute;
    this.requests = [];
  }

  async makeRequest(url, options = {}) {
    // Remove requests older than 1 minute
    const now = Date.now();
    this.requests = this.requests.filter(time => now - time < 60000);

    // Check if we're at the limit
    if (this.requests.length >= this.maxRequests) {
      const oldestRequest = Math.min(...this.requests);
      const waitTime = 60000 - (now - oldestRequest);
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }

    // Make the request
    this.requests.push(Date.now());
    
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'X-MCP-API-Key': this.apiKey
      }
    });
  }
}

Error Handling

Handle authentication errors gracefully:

async function authenticatedMCPRequest(url) {
  try {
    const response = await fetch(url, {
      headers: {
        'X-MCP-API-Key': process.env.APPIZER_MCP_API_KEY
      }
    });

    if (response.status === 401) {
      throw new Error('MCP authentication failed. Check your API key.');
    }

    if (response.status === 403) {
      throw new Error('MCP access forbidden. Check your permissions.');
    }

    return await response.json();
  } catch (error) {
    console.error('MCP request failed:', error.message);
    throw error;
  }
}

Next Steps

Previous
MCP Server
Next
Resources