Voiceflow MCP Client

A Node.js client that integrates with remote MCP servers to provide tools for Voiceflow Agents.

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

- 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

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

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

- 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.

- Copy.env.templateto create a new.envfile:

- Update the.envfile with your actual values:

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"]}}

- 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)

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

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

Create aservers-config.jsonfile 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"] } } }

- Command-based servers (usingcommandandargs)
- Environment variable substitution (using${VARIABLE_NAME})
- Disabling servers (usingdisabled: true)
- Auto-approval for specific tools (usingautoApprove)

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 theZAPIER_MCP_URLenvironment variable. The architecture supports adding more dynamic servers in the future.

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

docker run -p 3000:3000 \ --env-file .env \ --name mcp-client \ mcp-client

Or using Docker Compose (create adocker-compose.ymlfile):

services: mcp-client: build: . ports: - "3135:3135" env_file: - .env volumes: - ./logs:/app/logs restart: unless-stopped

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

The following directories are available for volume mounting:

- /app/logs: Application logs
- /app/public: Static files

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

Common Docker commands for managing the container:

# Stop the container docker stop mcp-client # Start the container docker start mcp-client # View logs docker logs mcp-client # Remove the container docker rm mcp-client # Rebuild and restart with new changes docker-compose up -d --build

- Start the API server on port 3000 (or the port specified in your .env file)
- Automatically connect to configured remote MCP servers when needed

This project supports integrating with remote MCP servers. You can configure them using aservers-config.jsonfile in the project root:

{ "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"] } } }

- Command-based servers (usingcommandandargs)
- Environment variable substitution (using${VARIABLE_NAME})
- Disabling servers (usingdisabled: true)
- Auto-approval for specific tools (usingautoApprove)

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 theZAPIER_MCP_URLenvironment variable. The architecture supports adding more dynamic servers in the future.

Returns the current status of the API and available MCP servers.

{ "status": "ok", "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--headless"], "disabled": false }, "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }, "disabled": false }, "time-mcp": { "command": "npx", "args": ["-y", "time-mcp"], "disabled": false }, "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"], "disabled": false } } }

Process a user query using available MCP tools and Claude AI.

{ "query": "What is the weather in New York?", "conversationId": "optional-conversation-id", "userId": "optional-user-id", "userEmail": "optional-user-email", "queryTimeoutMs": 30000, "llm_answer": false }

{ "query": "What is the weather in New York?", "answer": "The AI's response here", "conversationId": "conv-123456789", "userId": "user-123", "needsClarification": false, "noAnswer": false, "error": false, "toolResponses": [ { "tool": "weather_getWeather", "input": { "location": "New York" }, "response": "The current temperature is 72°F with sunny conditions.", "server": "weather" } ] }

WhenLAST_RESPONSE_ONLY=trueis set in the environment, only the last tool response will be returned. For example, if multiple tools are called:

{ "toolResponses": [ { "tool": "time_getTime", "input": { "location": "New York" }, "response": "The current time is 2:30 PM EDT", "server": "time" } ] }

- query(required): The user's question or request
- conversationId(optional): ID to maintain conversation context. If not provided, a new conversation will be created
- userId(optional): ID of the user making the request
- userEmail(optional): Email of the user, used for calendar-related tools
- queryTimeoutMs(optional): Maximum time in milliseconds to wait for a response. Defaults to 30000ms (30 seconds)
- llm_answer(optional): Whether to generate a final answer using Claude. If false, only tool responses will be returned. Defaults to false.

The API will return a JSON response with:

- query: The original query
- answer: The AI's response (null if llm_answer is false)
- conversationId: The ID of the conversation (new or existing)
- userId: The ID of the user (if provided)
- needsClarification: Boolean indicating if the AI needs more information
- noAnswer: Boolean indicating if the AI cannot answer the query with available tools
- error: Boolean indicating if an error occurred
- toolResponses: Array of tool responses, each containing:

- tool: The name of the tool that was called
- input: The input parameters passed to the tool
- response: The response from the tool
- server: The name of the MCP server that provided the tool
- error: Boolean indicating if the tool call failed (only present if true)

Retrieves all conversations for a specific user.

- userId(path parameter): The ID of the user

{ "userId": "user-123", "conversations": [ { "conversationId": "conv-123456789", "firstMessage": "What is the weather in New York?", "lastMessage": "The current temperature is 72°F with sunny conditions.", "messageCount": 4 } ] }

DELETE /api/conversation/:conversationId

- conversationId(path parameter): The ID of the conversation to clear

{ "success": true, "message": "Conversation conv-123456789 cleared successfully" }

Clears all conversations for a specific user.

- userId(path parameter): The ID of the user

{ "success": true, "message": "All conversations for user user-123 cleared successfully" }

Retrieves information about all configured MCP servers and their available actions.

{ "success": true, "servers": { "weather-server": { "name": "weather-server", "actions": [ { "name": "getWeather", "description": "Get current weather for a location", "inputSchema": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or location" } }, "required": ["location"] } } ], "enabled": true }, "google-calendar": { "name": "google-calendar", "actions": [ { "name": "listEvents", "description": "List calendar events", "inputSchema": { "type": "object", "properties": { "maxResults": { "type": "number", "description": "Maximum number of events to return" } } } } ], "enabled": true } } }

- success: Boolean indicating if the request was successful
- servers: Object containing information about each configured server:

- name: The server's name
- actions: Array of available actions for the server, each containing:

- name: The action name
- description: Description of what the action does
- inputSchema: JSON Schema describing the expected input parameters

curl -X POST http://localhost:3000/api/query \ -H "Content-Type: application/json" \ -d '{ "query": "What is the weather in New York?", "llm_answer": false }'

To test the integration, you can use the demo agent fileMCP Agent Apr 1 2025.vf. This agent is configured to work with the MCP client and includes the MCP Tools function.

Note: The demo agent is designed to showcase the integration capabilities and may need to be updated with your specific API keys and configurations.

The client includes several error handling mechanisms:

- Retry mechanism for connection failures
- Proper cleanup of resources
- Detailed logging for debugging

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.