Skip to main content
Glama
Sign In
deenesjakoruzh
Mantracare-Org

LiveKit MCP Server

by Mantracare-Org
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Servidor MCP de LiveKit

Python uv MCP Code style: ruff Tests

Un servidor de Protocolo de Contexto de Modelo (MCP 2.0) de alto rendimiento que conecta Agentes de IA con el Motor de Voz y Telefonía MantraCare LiveKit.

Arquitectura • Inicio rápido • Configuración • Conexión de clientes • Autenticación • Herramientas • Desarrollo

📖 Descripción general

El Servidor MCP de LiveKit permite a los LLM y asistentes de codificación con IA (como Antigravity, Claude, Cursor y agentes personalizados) controlar, inspeccionar y activar de forma segura canalizaciones de telefonía de voz impulsadas por LiveKit (~/lkt) y autenticadas mediante Mantra Auth (~/mantra-auth).

Capacidades clave

  • 🚀 Cumplimiento con MCP 2.0: Construido sobre el SDK oficial de Python mcp utilizando transportes de Eventos Enviados por el Servidor (SSE) y HTTP Streamable.

  • 🔐 Seguridad OAuth 2.1 y JWT compartido: Validación nativa de JWT HS256 que coincide con mantra-auth, con soporte tanto para cabeceras Authorization: Bearer como para parámetros de consulta ?token=.

  • ⚡ Núcleo asíncrono ultrarrápido: Impulsado por Starlette, Uvicorn y la gestión de paquetes uv.

  • 🧩 Arquitectura de herramientas modular: Herramientas separadas por dominio para telefonía, análisis de llamadas, búsqueda en la base de conocimiento y troncales SIP.

  • 🧠 Memoria agéntica: Base de conocimiento completa de Obsidian (obsidian/) y reglas AGENTS.md para la preservación del contexto en la programación en pareja con IA.

Related MCP server: Agent Identity MCP Server

🏛️ Arquitectura del sistema

┌─────────────────────────────────────────────────────────────┐
│ AI Client (Cursor / Claude / Antigravity / Web Agent)       │
└──────────────────────────────┬──────────────────────────────┘
                               │ 1. Bearer Token / ?token= (OAuth 2.1)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ [3. mantra-auth (:3000)]                                    │
│ Next.js + Prisma OAuth 2.1 Authorization Server             │
│ - Issues HS256 JWTs and verifies via /api/oauth/introspect  │
└──────────────────────────────┬──────────────────────────────┘
                               │ Shared JWT Secret Verification
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ [2. livekit-mcp (:8000)] (This Server)                      │
│ - Starlette ASGI + MCP 2.0 SSE Transport                    │
│ - Pure ASGI Auth Middleware (HS256 JWT validation)          │
│ - Public Endpoints: /health, /                              │
│ - Protected Endpoints: /sse, /messages                      │
│ - Registered Tools: greet_user, [Telephony/KB/SIP coming]   │
└──────────────────────────────┬──────────────────────────────┘
                               │ 2. Async HTTP (REST)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ [1. lkt (:8081)]                                            │
│ MantraCare LiveKit Voice Agent & Telephony Engine           │
│ - SIP Trunks (Plivo, Zadarma, VoiceLink, Twilio)            │
│ - LiveKit Cloud WebRTC Rooms & STT→LLM→TTS Voice Pipeline   │
│ - PostgreSQL (call_logs, kb_pages) & Redis (queues, locks)  │
└─────────────────────────────────────────────────────────────┘

📁 Estructura del repositorio

livekit-mcp/
├── .env.example                # Sample environment variables
├── .gitignore                  # Git ignore definitions
├── .python-version             # Python version pin (3.11)
├── AGENTS.md                   # Agent Memory instructions
├── dev.sh                      # Development startup script
├── pyproject.toml              # UV package specification & build settings
├── uv.lock                     # Deterministic lockfile
├── README.md                   # Project documentation
│
├── obsidian/                   # Permanent Agentic Knowledge Base
│   ├── Home.md                 # Project navigation hub
│   ├── Architecture/           # System design, data flow, security & APIs
│   ├── Context/                # Stack, project summary & repository map
│   ├── Development/            # Sprint tracking, TODO & Changelog
│   ├── Features/               # Feature specifications (tools, auth)
│   └── Knowledge/              # Coding standards & architectural conventions
│
├── src/
│   └── livekit_mcp/
│       ├── __init__.py
│       ├── config.py           # Pydantic Settings & environment validation
│       ├── server.py           # MCPServer & Starlette app factory
│       ├── main.py             # CLI runner with Uvicorn
│       ├── auth/
│       │   ├── __init__.py
│       │   ├── jwt.py          # HS256 JWT decoding & claims validation
│       │   └── middleware.py   # Pure ASGI auth middleware (headers & ?token=)
│       ├── clients/
│       │   ├── __init__.py
│       │   ├── lkt_client.py   # Async HTTP client for lkt FastAPI (:8081)
│       │   └── auth_client.py  # Async HTTP client for mantra-auth (:3000)
│       └── tools/
│           ├── __init__.py
│           └── greeting.py     # Initial `greet_user` verification tool
│
└── tests/
    ├── __init__.py
    ├── conftest.py             # Fixtures for tokens, settings & test client
    ├── test_config.py          # Configuration unit tests
    ├── test_auth.py            # JWT verification & claims unit tests
    ├── test_greeting.py        # Tool registration & execution tests
    └── test_server.py          # Endpoints, SSE & Auth integration tests

🚀 Inicio rápido

1. Requisitos previos

  • Python: 3.11 o superior

  • uv: Gestor de paquetes de Python rápido (Instalar uv)

    curl -LsSf https://astral.sh/uv/install.sh | sh

2. Instalación y configuración

  1. Clona el repositorio y entra en el directorio:

    cd ~/livekit-mcp

  2. Crea la configuración de tu entorno:

    cp .env.example .env

  3. Instala las dependencias con uv:

    uv sync

3. Ejecución del servidor

Inicia el servidor de desarrollo con recarga automática:

./dev.sh

O ejecútalo directamente usando uv:

uv run python -m livekit_mcp.main

El servidor estará disponible en http://localhost:8000.

⚙️ Configuración

Todos los ajustes se gestionan en src/livekit_mcp/config.py usando pydantic-settings y se cargan desde .env:

Variable

Tipo

Valor predeterminado

Descripción

HOST

cadena

0.0.0.0

Dirección de enlace del servidor

PORT

entero

8000

Puerto de escucha del servidor

ENVIRONMENT

cadena

development

development, test o production

LOG_LEVEL

cadena

INFO

Nivel de registro (DEBUG, INFO, WARNING, ERROR)

AUTH_ENABLED

booleano

true

Aplicar autenticación JWT en los endpoints protegidos

JWT_SECRET

cadena

your-super-secret-...

Clave secreta compartida para la verificación de firma JWT HS256

JWT_ALGORITHM

cadena

HS256

Algoritmo de firma JWT (coincide con mantra-auth)

AUTH_SERVER_URL

cadena

http://localhost:3000

URL base del servidor Mantra Auth

JWT_ISSUER

cadena

http://localhost:3000

Reclamación de emisor JWT esperada (iss)

JWT_AUDIENCE

cadena

(vacío)

Reclamación de audiencia esperada opcional (aud)

LKT_API_BASE_URL

cadena

http://localhost:8081

URL base de la API del Agente de Voz LKT

LKT_API_TIMEOUT

flotante

15.0

Tiempo de espera de solicitud HTTP en segundos para llamadas LKT

LIVEKIT_URL

cadena

(vacío)

URL WebSocket directa de LiveKit Cloud (opcional)

LIVEKIT_API_KEY

cadena

(vacío)

Clave de API directa de LiveKit Cloud (opcional)

LIVEKIT_API_SECRET

cadena

(vacío)

Secreto de API directo de LiveKit Cloud (opcional)

📡 Endpoints

Endpoint

Método

Autenticación requerida

Descripción

/health

GET

❌ No

Comprobación pública de salud y disponibilidad que devuelve el estado del servicio

/

GET

❌ No

Estado del servicio y metadatos de los endpoints

/sse

GET

✅ Sí

Abre un flujo persistente de Eventos Enviados por el Servidor (SSE) para clientes MCP

/messages

POST

✅ Sí

Endpoint JSON-RPC 2.0 para solicitudes MCP (ejecución de herramientas, listados)

Ejemplo de comprobación de salud

curl http://localhost:8000/health
{
  "status": "healthy",
  "service": "livekit-mcp",
  "version": "0.1.0",
  "auth_enabled": true,
  "environment": "development",
  "lkt_api_configured": true,
  "timestamp": "2026-08-20T12:30:00.000000+00:00"
}

🔐 Autenticación

El servidor implementa Autenticación JWT compartida OAuth 2.1 / HS256 compatible con mantra-auth.

Cómo proporcionar las credenciales

  1. Cabecera de autorización (estándar):

    GET /sse HTTP/1.1
Host: localhost:8000
Authorization: Bearer <your-jwt-access-token>

  2. Parámetro de consulta (para clientes SSE / EventSource):

    GET /sse?token=<your-jwt-access-token> HTTP/1.1
Host: localhost:8000

Reclamaciones JWT esperadas

{
  "sub": "user-123",
  "aud": "client-app",
  "iss": "http://localhost:3000",
  "exp": 1755694800,
  "iat": 1755691200,
  "scope": "openid profile telephony:call",
  "token_type": "access_token"
}

Consejo de desarrollo: Establece AUTH_ENABLED=false en .env para desactivar la verificación de tokens durante las pruebas locales.

🛠️ Herramientas disponibles

1. greet_user

Una herramienta de verificación que valida la conectividad MCP, el análisis de parámetros y el estado del servidor.

  • Parámetros:

    • name (cadena, obligatorio): Nombre del usuario o agente que invoca la herramienta.

    • message (cadena, opcional): Mensaje de saludo personalizado.

  • Devuelve:

    👋 Hello, Alice!

Welcome to MantraCare LiveKit MCP!

--- System Status ---
• Service: LiveKit MCP Server
• Status: Operational & Ready
• Timestamp: 2026-08-20T12:30:00.000000+00:00
• Protocol: MCP 2.0 (SSE / HTTP)

🔌 Conexión de clientes MCP

1. Antigravity / CLI de Gemini (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "livekit": {
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}

2. IDE de Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "livekit": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer <YOUR_JWT_TOKEN>"
      }
    }
  }
}

3. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "livekit": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/fardeen/livekit-mcp",
        "run",
        "python",
        "-m",
        "livekit_mcp.main"
      ],
      "env": {
        "AUTH_ENABLED": "false"
      }
    }
  }
}

🧪 Desarrollo y pruebas

Ejecución de pruebas

El proyecto incluye un conjunto completo de pruebas que cubren configuración, verificación JWT, middleware y herramientas:

uv run pytest -v

Formato de código y linting

Aplica estándares de codificación limpios usando ruff:

# Check code
uv run ruff check .

# Auto-fix issues & format
uv run ruff check --fix .
uv run ruff format .

Añadir nuevas herramientas

Para añadir una nueva herramienta a livekit-mcp:

  1. Crea un módulo en src/livekit_mcp/tools/<dominio>.py.

  2. Define una función de registro:

    from mcp.server.mcpserver import MCPServer

def register_telephony_tools(server: MCPServer) -> None:
    @server.tool(name="trigger_call", description="Trigger an outbound call")
    async def trigger_call(phone_number: str, prompt: str) -> str:
        # Call LktClient here
        return f"Call initiated to {phone_number}"

  3. Registra la función en src/livekit_mcp/server.py dentro de create_mcp_server().

  4. Añade pruebas unitarias en tests/test_<dominio>.py.

📚 Memoria agéntica

Este repositorio sigue el patrón de Memoria agéntica. Antes de realizar cambios arquitectónicos, revisa el repositorio de conocimiento de Obsidian en obsidian/:

  • obsidian/Home.md — Centro de navegación del proyecto

  • obsidian/Architecture/Overview.md — Diseño del sistema y topología

  • obsidian/Development/Current Sprint.md — Estado de desarrollo activo

  • obsidian/Development/TODO.md — Hoja de ruta próxima

  • obsidian/Knowledge/Coding Standards.md — Convenciones de código

📄 Licencia

Propietaria © MantraCare. Todos los derechos reservados.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers