Labsco
voiceflow-community logo

Voiceflow MCP Client

★ 2

from voiceflow-community

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

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#email#automation#calendar#scraping#browser#cloud#devops#git

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

API Endpoints

Health Check

GET /

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

Response:

{
  "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 Query

POST /api/query

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

Request body:

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

Response:

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

When LAST_RESPONSE_ONLY=true is 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"
    }
  ]
}

Available parameters:

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

Get User Conversations

GET /api/conversations/:userId

Retrieves all conversations for a specific user.

Parameters:

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

Response:

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

Clear Conversation

DELETE /api/conversation/:conversationId

Clears a specific conversation.

Parameters:

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

Response:

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

Clear User Conversations

DELETE /api/conversations/:userId

Clears all conversations for a specific user.

Parameters:

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

Response:

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

Get Available Servers

GET /api/servers

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

Response:

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

The response includes:

  • 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
    • enabled: Boolean indicating if the server is enabled
    • error: Error message (only present if the server failed to provide its actions)

Testing the API

You can test the API using curl:

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
  }'

Or use the included demo:

node demo.js

Testing with Demo Agent

To test the integration, you can use the demo agent file MCP 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.

Development

  • Run in development mode: npm run dev

Error Handling

The client includes several error handling mechanisms:

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