Voiceflow MCP Client

A Node.js client for the Model Context Protocol (MCP) that integrates with remote MCP servers to provide tools for your Voiceflow Agent.

Features

- Support for multiple remote MCP servers
- HTTP transport for server communication
- Tool discovery and integration with Claude AI
- Configurable server integration through JSON
- Automatic error handling and retries

Setup

Prerequisites

- Node.js 20.x or higher
- npm

Installation

1. Clone the repository with submodules:

git clone --recursive https://github.com/voiceflow-gallagan/voiceflow-mcp-server-client.git

Or if you've already cloned the repository, initialize the submodules:

git submodule update --init --recursive

2. Install dependencies:

npm install

3. Build the MCP servers:

npm run build

This will:
- Set up Playwright dependencies (including Chrome and Chromium)
- Initialize and update Git submodules (weather-mcp-server and google-calendar-mcp)
- Build the weather MCP server
- Build the Google Calendar MCP server

Note: The build process requires root access to install Chrome. You may be prompted for your password.

4. Set up environment variables:
- Copy .env.template to create a new .env file:

   cp .env.template .env

   

   ANTHROPIC_API_KEY=your-anthropic-api-key

   CLAUDE_MODEL=claude-3-7-sonnet-20250219

   PORT=3000

   BRAVE_API_KEY=your-brave-api-key

   LAST_RESPONSE_ONLY=false

   SERVER_DISCOVERY_TIMEOUT=20000

   ZAPIER_MCP_URL=https://actions.zapier.com/mcp/your-api-key/sse

   MAX_CONVERSATION_HISTORY=10

   TRUNCATE_TOOL_RESPONSES=false

   GCP_SAVED_TOKENS={"access_token":"your-access-token","scope":"https://www.googleapis.com/auth/calendar","token_type":"Bearer","expiry_date":1234567890,"refresh_token":"your-refresh-token"}

   GCP_OAUTH_KEYS={"installed":{"client_id":"your-client-id","project_id":"your-project-id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_secret":"your-client-secret","redirect_uris":["http://localhost"]}}

   

Required environment variables:
- ANTHROPIC_API_KEY: Your Anthropic API key for Claude AI
- CLAUDE_MODEL: The Claude model to use (default: claude-3-7-sonnet-20250219)
- PORT: The port number for the server (default: 3000)
- BRAVE_API_KEY: Your Brave Search API key for search functionality
- LAST_RESPONSE_ONLY: When set to "true", only the last tool response will be returned in the API response (default: false)
- SERVER_DISCOVERY_TIMEOUT: Maximum time in milliseconds to wait for server discovery (default: 20000ms)
- ZAPIER_MCP_URL: Optional URL for the Zapier MCP server (e.g., https://actions.zapier.com/mcp/your-api-key/sse)
- MAX_CONVERSATION_HISTORY: Maximum number of messages to keep in conversation history (default: 10)
- TRUNCATE_TOOL_RESPONSES: Whether to truncate tool responses in the toolResponses array (default: false)
- When true, tool responses will be truncated to 1000 characters
- When false, full responses will be kept in toolResponses
- Note: Tool responses in the conversation context are always truncated to prevent token limit issues
- MAX_FOLLOWUP_STEPS: Maximum number of recursive tool calls allowed (default: 5)
- Higher values allow more complex tasks but may increase processing time
- Lower values prevent infinite loops but may limit task completion
- PLAYWRIGHT_EXTENDED_STEPS: Maximum number of recursive tool calls allowed for playwright tools (default: 8)
- Separate limit for web browsing tools which often require more steps
- Increase this value for complex web browsing scenarios

Optional environment variables:
- GCP_SAVED_TOKENS: Google Calendar OAuth tokens (optional)
- GCP_OAUTH_KEYS: Google Calendar OAuth credentials (optional)

Dynamic Server Configuration

The client supports dynamic server configuration through environment variables. Currently, this feature is only available for the Zapier MCP server. This allows you to:
- Enable/disable the Zapier server without modifying the code
- Configure the Zapier server with your API key securely
- Add the Zapier server without code changes

Example of dynamic server configuration:
1. Add the Zapier server URL to your .env file:

   ZAPIER_MCP_URL=https://actions.zapier.com/mcp/your-api-key/sse

   

2. The Zapier server will be automatically configured when the application starts.

3. To disable the Zapier server, simply remove or comment out the ZAPIER_MCP_URL environment variable.

Note: While the dynamic server configuration feature is currently limited to the Zapier server, the architecture supports adding more dynamic servers in the future.

Google Calendar Setup

To use the Google Calendar MCP server, you need to set up OAuth 2.0 credentials and add them to your environment variables:

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API
4. Create OAuth 2.0 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as the application type
- Download the client configuration file

5. Add these environment variables to your .env file:

   GCP_SAVED_TOKENS={"access_token":"your-access-token","scope":"https://www.googleapis.com/auth/calendar","token_type":"Bearer","expiry_date":1234567890,"refresh_token":"your-refresh-token"}

   GCP_OAUTH_KEYS={"installed":{"client_id":"your-client-id","project_id":"your-project-id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_secret":"your-client-secret","redirect_uris":["http://localhost"]}}

   

Note: The values should be the entire JSON content as a single line. You can get these values from:
- GCP_SAVED_TOKENS: After the first OAuth flow, the tokens will be saved in .gcp-saved-tokens.json
- GCP_OAUTH_KEYS: From the downloaded client configuration file

4. Create a servers-config.json file in the root directory to configure your remote MCP servers:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "time-mcp": {
      "command": "npx",
      "args": ["-y", "time-mcp"]
    },
    "weather-server": {
      "command": "node",
      "args": ["mcp-servers/weather-mcp-server/build/index.js"],
      "env": {
        "OPENWEATHER_API_KEY": "${OPENWEATHER_API_KEY}"
      },
      "disabled": false,
      "autoApprove": []
    },
    "google-calendar": {
      "command": "node",
      "args": ["./mcp-servers/google-calendar-mcp/build/index.js"]
    }
  }
}

Server configuration supports:
- Command-based servers (using command and args)
- Environment variable substitution (using ${VARIABLE_NAME})
- Disabling servers (using disabled: true)
- Auto-approval for specific tools (using autoApprove)

For each server, tools will be prefixed with the server name to avoid conflicts (e.g., weather_getWeather).

Currently, dynamic server configuration through environment variables is only supported for the Zapier server. This allows you to configure the Zapier server's URL and API key through the ZAPIER_MCP_URL environment variable. The architecture supports adding more dynamic servers in the future.

Docker Setup

Prerequisites

- Docker installed on your system
- Docker Compose (optional, for easier management)

Building and Running with Docker

1. Build the Docker image:

docker build -t mcp-client .

2. Run the container:

docker run -p 3000:3000 \

  --env-file .env \

  --name mcp-client \

  mcp-client

Or using Docker Compose (create a docker-compose.yml file):

services:

  mcp-client:

    build: .

    ports:

      - "3135:3135"

    env_file:

      - .env

    volumes:

      - ./logs:/app/logs

    restart: unless-stopped

Then run:

docker-compose up -d

Docker Environment Variables

The Docker container uses the same environment variables as the local setup. Make sure your .env file is properly configured before building the image.

Docker Volumes

The following directories are available for volume mounting:
- /app/logs: Application logs
- /app/public: Static files

Docker Health Check

The container includes a health check endpoint at /health. You can monitor the container's health using:

docker inspect --format='{{.State.Health.Status}}' mcp-client

Docker Commands

Common Docker commands for managing the container:

```bash