Ringba API MCP Server

Streamable HTTP MCP server that exposes Ringba analytics APIs as tools for AI-assisted workflows — starting with EHG insights reports, with more Ringba endpoints to follow.

Quick Start

npm install
cp .env.example .env   # then edit .env with your credentials
npm run build
npm start

The server listens on http://0.0.0.0:3031/mcp-ringba by default. Point your MCP client at that URL.

Client Setup Guides

All clients below assume the server is running. Start it first:

npm start

For production use, run it under a process manager (PM2, systemd, launchd, or a simple nohup / background task).

Claude Code (CLI)

Add this to your Claude Code settings. The location depends on your scope:

{
  "mcpServers": {
    "ringba-api": {
      "type": "http",
      "url": "http://localhost:3031/mcp-ringba"
    }
  }
}

Restart Claude Code or run /mcp to verify the server is connected.

The ringba_insights and ringba_list_available_columns tools will appear in Claude's tool list automatically.

Claude Desktop

Claude Desktop supports HTTP MCP servers directly. Open the config file:

{
  "mcpServers": {
    "ringba-api": {
      "type": "http",
      "url": "http://localhost:3031/mcp-ringba"
    }
  }
}

Restart Claude Desktop after saving. The Ringba tools will be listed under the tools panel (hammer icon) in the chat input.

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "ringba-api": {
      "url": "http://localhost:3031/mcp-ringba"
    }
  }
}

You can also place this at ~/.cursor/mcp.json for global access across all projects. Restart Cursor after adding the configuration.

Cursor discovers MCP tools automatically; use Cmd/Ctrl+I to open Composer and the tools will be available.

GitHub Copilot (VS Code / VS Code Insiders)

GitHub Copilot supports MCP servers through the .vscode/mcp.json file (VS Code 1.99+ with Copilot Chat). Create it in your project root:

{
  "servers": {
    "ringba-api": {
      "type": "http",
      "url": "http://localhost:3031/mcp-ringba"
    }
  }
}

After saving, open the Copilot Chat panel. Copilot will auto-discover the MCP tools on the next prompt.

Codex (OpenAI)

Codex supports MCP via its agent configuration. Add a server entry in your Codex config file (~/.codex/config.toml or project .codex.toml):

[mcp_servers.ringba-api]
url = "http://localhost:3031/mcp-ringba"

If running Codex in a container or remote environment, replace localhost with the host machine's reachable IP.

Windsurf

Create or edit .windsurf/mcp.json in your project:

{
  "mcpServers": {
    "ringba-api": {
      "url": "http://localhost:3031/mcp-ringba"
    }
  }
}

Use Cascade (Cmd+L) after restart — the tools will be available to the agent.

Continue (VS Code / JetBrains extension)

Add to ~/.continue/config.json under the mcpServers key:

{
  "mcpServers": [
    {
      "name": "ringba-api",
      "transport": "http",
      "url": "http://localhost:3031/mcp-ringba"
    }
  ]
}

Continue will connect on the next chat session.

Generic / Other Clients

This server speaks standard JSON-RPC 2.0 over Streamable HTTP at the configured MCP_PATH. Any MCP-compatible client that supports the streamable-http transport can connect.

Architecture

Client (Claude Code / IDE)
  │
  │  JSON-RPC 2.0 over Streamable HTTP
  ▼
ringba-api-mcp  (TypeScript, @modelcontextprotocol/sdk)
  │
  │  POST  Authorization: Token <api_key>
  ▼
Ringba API  (api.ringba.com/v2/{accountId}/insights)

• Transport: Streamable HTTP (/mcp-ringba), stateless, no session IDs

• Auth: Ringba API token in Authorization header on upstream calls

• Port/Host: Configurable via MCP_PORT / MCP_HOST (defaults: 3031 / 0.0.0.0)

• CORS: Open (*) for local tooling

Environment Variables

The server also loads ../RingbaApi/.env and ../RingbaApi/.env.local if they exist, so you can share credentials with the main RingbaApi project.

Tools

ringba_insights

Run an EHG insights report — group call data by a dimension and get aggregated metrics for a date range.

Required parameters:

Optional parameters:

Filter syntax:

Each filter object wraps an anyConditionToMatch array of conditions:

{
  "column": "targetName",
  "value": "Elevated",
  "isNegativeMatch": false,
  "comparisonType": "CONTAINS"
}

Supported comparison types: CONTAINS, EQUALS, STARTS_WITH, ENDS_WITH, GREATER_THAN, LESS_THAN, and others provided by the Ringba API.

Example call via MCP:

{
  "name": "ringba_insights",
  "arguments": {
    "reportStart": "2026-06-11T06:00:00Z",
    "reportEnd": "2026-06-18T05:59:59Z",
    "groupByColumn": "targetName",
    "filters": [
      {
        "anyConditionToMatch": [
          {
            "column": "targetName",
            "value": "Elevated",
            "isNegativeMatch": false,
            "comparisonType": "CONTAINS"
          }
        ]
      }
    ]
  }
}

ringba_list_available_columns

Reference tool — returns all known columns you can use in groupByColumn, valueColumns, orderByColumn, and filters.

Optional parameter:

Available group-by dimensions:

targetName, publisherName, campaignName, buyerName, inboundNumber, callerId, callStatus, tag:InboundNumber:State, tag:InboundNumber:City, tag:InboundNumber:Zip

Default value metrics (20 columns):

callCount, liveCallCount, completedCalls, endedCalls, connectedCallCount, nonConnectedCallCount, duplicateCalls, blockedCalls, incompleteCalls, payoutCount, convertedCalls, conversionAmount, payoutAmount, profitGross, profitMarginGross, earningsPerCallGross, totalCost, callLengthInSeconds, avgHandleTime, convertedPercent

Extending

This server is scoped to ringba-api-mcp so additional Ringba endpoints (number management, campaign config, etc.) can be added as new tools under the same server without breaking existing clients.

To add a new endpoint:

1. Add a tool definition in ListToolsRequestSchema handler

2. Add a case in the CallToolRequestSchema switch

3. Write a handler that calls the Ringba API via fetch()

4. Add any new column definitions to AVAILABLE_COLUMNS if needed

Differences from db-mcp-server