Elba MCP Server

Why?

Building voice AI agents usually means clicking through a dashboard. With this MCP server, you can do it all from your editor:

• Create agents with a prompt — describe what you want, your AI assistant builds it

• Iterate fast — change system prompts, swap voices, test — all without leaving your IDE

• Version control — agent configs live in your workflow, not trapped in a dashboard

• Zero context switching — ask Claude or Cursor to manage your agents directly

Elba is a voice AI agent platform by Kolsetu. This MCP server is a thin client that translates MCP tool calls into Elba API requests — all business logic lives in the Elba platform.

Related MCP server: SideButton

Quick Start

1. Get your integration token

Go to Elba Dashboard → Settings → Integrations → Copy your token.

2. Add to your MCP client

claude mcp add elba -- -e ELBA_INTEGRATION_TOKEN=your-token-here npx -y @kolsetu-opensource/elba-mcp-server

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "elba": {
      "command": "npx",
      "args": ["-y", "@kolsetu-opensource/elba-mcp-server"],
      "env": {
        "ELBA_INTEGRATION_TOKEN": "your-token-here"
      }
    }
  }
}

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "elba": {
      "command": "npx",
      "args": ["-y", "@kolsetu-opensource/elba-mcp-server"],
      "env": {
        "ELBA_INTEGRATION_TOKEN": "your-token-here"
      }
    }
  }
}

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "elba": {
        "command": "npx",
        "args": ["-y", "@kolsetu-opensource/elba-mcp-server"],
        "env": {
          "ELBA_INTEGRATION_TOKEN": "your-token-here"
        }
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "elba": {
      "command": "npx",
      "args": ["-y", "@kolsetu-opensource/elba-mcp-server"],
      "env": {
        "ELBA_INTEGRATION_TOKEN": "your-token-here"
      }
    }
  }
}

3. Start using it

Once connected, ask your AI assistant things like:

• "List all my Elba agents"

• "Create a new voice agent called 'Support Bot' that handles customer billing questions"

• "What voices are available? Switch my agent to use a different voice"

• "Update the system prompt for my agent to be more friendly"

Available Tools

Architecture

┌─────────────────┐     stdio      ┌──────────────────┐     HTTPS     ┌──────────────┐
│   MCP Client    │◄──────────────►│  Elba MCP Server │◄────────────►│  Elba API    │
│ (Claude, Cursor │                │  (this project)  │              │  (backend)   │
│  VS Code, etc.) │                │  Thin client     │              │              │
└─────────────────┘                └──────────────────┘              └──────────────┘

• Thin client — no business logic here; the server translates MCP calls into API requests

• Local execution — runs as a stdio child process, no network exposure

• Org-scoped tokens — each integration token is limited to a single organization

Roadmap

Phase 1 — Core Agent Management ✅

Phase 2 — Deploy & Test

Phase 3 — IVR & Telephony

Security

This project takes supply chain security seriously:

Authentication

1. Log in to Elba

2. Go to Settings → Integrations

3. Generate or copy your integration token

4. Set it as ELBA_INTEGRATION_TOKEN in your MCP client config

Tokens are scoped to your organization — they can only access agents and data within your org.

Vulnerability Reporting

Do NOT open public issues for security vulnerabilities. See SECURITY.md for responsible disclosure via GitHub Security Advisories.

Development

# Clone the repo
git clone https://github.com/Kolsetu-Opensource/elba-mcp-server.git
cd elba-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type-check
npm run typecheck

# Lint
npm run lint

# Start in dev mode
npm run dev

Requires Node.js ≥ 20 (see .nvmrc).

Project Structure

src/
├── index.ts          # CLI entry point
├── server.ts         # MCP server init, tool registration
├── config.ts         # Environment config
├── auth.ts           # Token format validation
├── elba-client.ts    # Elba API client
└── tools/
    ├── list-agents.ts
    ├── list-voices.ts
    └── upsert-agent.ts
__tests__/            # Mirrors src/ structure (vitest)

Troubleshooting

"ELBA_INTEGRATION_TOKEN environment variable is required"

Make sure you've set the token in your MCP client config. See Quick Start for examples.

"Invalid or expired integration token"

Your token may have been revoked or expired. Generate a new one from Elba Dashboard → Settings → Integrations.

Server not starting

1. Check you're running Node.js ≥ 20: node --version

2. Try running directly: ELBA_INTEGRATION_TOKEN=your-token npx @kolsetu-opensource/elba-mcp-server

3. Check your MCP client logs for error messages

Still stuck?

• Open a discussion for questions

• File an issue for bugs

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Quick version:

# Make your changes, then:
npm run lint && npm run typecheck && npm test
npx changeset    # describe your change
git commit -s     # sign-off required (DCO)

License

MIT — see LICENSE for details.