Super Singularity MCP Server

A Model Context Protocol (MCP) server for integrating Claude Desktop with Super Singularity's course creation API, ElevenLabs text-to-speech, and Azure Blob Storage.

Features

Complete Course Management: Create, update, and manage courses
All Card Types: Support for content, quiz, poll, form, video, audio, and link cards
Text-to-Speech: Generate audio from text using ElevenLabs TTS
Cloud Storage: Upload and host audio files on Azure Blob Storage
Script Preservation: Store original script text in audio card contents
Production Ready: Environment configuration, error handling, and timeout management

Quick Start

Clone and Install:

git clone <repository-url>
cd mcp-servers
uv sync

Configure Environment:

cp .env.example .env
# Edit .env with your API keys and configuration

Add to Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "super-singularity": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp-servers/server.py"]
    }
  }
}

Restart Claude Desktop and start creating courses!

Environment Configuration

Required environment variables in .env:

# Super Singularity API
API_BASE_URL=https://your-api-domain.com
API_TOKEN=your-bearer-token-here  
COMPANY_ID=your-company-id-here

# ElevenLabs TTS
ELEVENLABS_API_KEY=your-elevenlabs-api-key-here
ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM

# Azure Blob Storage  
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
AZURE_CONTAINER_NAME=audio-files

Available Tools

Course Management

get_course(course_id) - Get course details
create_course(title, ...) - Create new course
get_course_cards(course_id) - Get all cards in course

Card Creation

create_content_card() - Text content with optional image
create_quiz_card() - Multiple choice questions
create_poll_card() - Opinion polls for collecting learner feedback
create_form_card() - Form inputs for collecting learner responses
create_video_card() - Video content
create_audio_card() - Audio content with optional script preservation
create_link_card() - External resource links

Audio Generation

generate_audio_from_text(text, title) - Generate audio using ElevenLabs TTS
Creates audio files and uploads to Azure Storage
Returns URL and script preservation instructions

Audio Card Workflow

Due to MCP limitations, audio card creation from script requires two steps:

Generate Audio:

generate_audio_from_text("Your script text here", "Audio Title")

Create Card with Script Preservation:

create_audio_card(course_id, audio_url, title, script="Your script text here")

The script parameter preserves the original text in the card contents for future reference.

MCP Limitations Discovered

The Problem

MCP tools that combine multiple async operations (ElevenLabs + Azure + API requests) cause "Internal Server Error" in Claude Desktop, regardless of function names or implementation approach.

Failed Attempts

All of these caused Internal Server Errors:

create_audio_card_from_script()
generate_audio_url_from_script()
create_audio_card_using_script()
test_helper_function_plus_api()

Working Solution

Separate tools for each operation:

generate_audio_from_text() - Only handles ElevenLabs + Azure
create_audio_card() - Only handles API requests
Two-step workflow with clear instructions for script preservation

Root Cause Analysis

The limitation appears to be related to:

Complex async operation chains in single MCP tools
Timeout thresholds for multi-step operations
Memory/resource constraints in Claude Desktop MCP client
Event loop handling of combined external service calls

Community Validation

Our findings align with known MCP issues documented in the community:

GitHub Issue #424: "MCP Timeout needs to be configurable"
GitHub Issue #417: "MCP Server Internal Server Error Report"
Multiple forum discussions about timeout errors and Internal Server Errors

Best Practices Learned

Keep MCP tools simple and atomic - Single responsibility per tool
Avoid combining multiple external service calls in one tool
Use helper functions for complex operations, but call them from separate tools
Provide clear instructions in tool responses to guide multi-step workflows
Test incrementally when adding new integrations

API Documentation

Complete API documentation available in: documentation/external-api-documentation.md

Dependencies

mcp - Model Context Protocol Python SDK
httpx - Async HTTP client for API requests
elevenlabs - ElevenLabs TTS integration
azure-storage-blob - Azure Blob Storage client
python-dotenv - Environment variable management

License

[Add your license here]

Contributing

[Add contributing guidelines here]