Skip to main content
Glama
pixxelboy

IRCAM Amplify MCP Server

by pixxelboy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

IRCAM Amplify MCP Server

MCP (Model Context Protocol) server for IRCAM Amplify audio processing APIs. Enables any MCP-compatible LLM to analyze music, separate stems, detect AI-generated audio, and more.

Features

  • Music Analysis: Extract genre, mood, tempo, key, and instruments from audio

  • Stem Separation: Split audio into vocals, drums, bass, and other instruments

  • AI Detection: Detect whether music is AI-generated or human-made

  • Loudness Analysis: Measure LUFS, true peak, and dynamic range

  • Async Job Handling: Poll long-running operations with progress tracking

Supported Audio Formats

MP3, WAV, FLAC, OGG, M4A (max 100MB)

Quick Start

Prerequisites

Installation

npm install -g ircam-amplify-mcp

Or run directly with npx:

npx ircam-amplify-mcp

Configuration

1. Set your API key

export IRCAM_AMPLIFY_API_KEY="your-api-key-here"

2. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ircam-amplify": {
      "command": "npx",
      "args": ["ircam-amplify-mcp"],
      "env": {
        "IRCAM_AMPLIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

Tool

Description

Input

Output

analyze_music

Extract genre, mood, tempo, key, instruments

audio_url

{ genre[], mood[], tempo, key, instruments[] }

separate_stems

Split into vocals, drums, bass, other

audio_url

{ vocals_url, drums_url, bass_url, other_url } or { job_id }

detect_ai_music

Detect AI vs human-made music

audio_url

{ confidence, classification }

analyze_loudness

Measure LUFS, peak, dynamic range

audio_url

{ integrated_lufs, true_peak_db, loudness_range }

check_job_status

Poll async operations

job_id

{ status, progress, result }

Usage Examples

Analyze a song

"Analyze this song: https://example.com/song.mp3"

Response:

{
  "genre": ["electronic", "house"],
  "mood": ["energetic", "uplifting"],
  "tempo": 128,
  "key": "A minor",
  "instruments": ["synthesizer", "drums", "bass"]
}

Separate stems

"Separate the vocals from this track: https://example.com/track.mp3"

Response (sync for short files):

{
  "vocals_url": "https://cdn.ircamamplify.io/stems/vocals.wav",
  "drums_url": "https://cdn.ircamamplify.io/stems/drums.wav",
  "bass_url": "https://cdn.ircamamplify.io/stems/bass.wav",
  "other_url": "https://cdn.ircamamplify.io/stems/other.wav"
}

Response (async for longer files):

{
  "job_id": "abc123-def456"
}

Check if AI-generated

"Is this track AI-generated? https://example.com/mystery.mp3"

Response:

{
  "confidence": 85,
  "classification": "ai_generated"
}

Classification values: ai_generated, human_made, or uncertain

Analyze loudness

"Check if this master is ready for Spotify: https://example.com/master.wav"

Response:

{
  "integrated_lufs": -14.0,
  "true_peak_db": -1.0,
  "loudness_range": 6.0
}

Check job status

"Check the status of job abc123-def456"

Response:

{
  "status": "completed",
  "progress": 100,
  "result": {
    "vocals_url": "...",
    "drums_url": "...",
    "bass_url": "...",
    "other_url": "..."
  }
}

Status values: pending, processing, completed, failed

Error Handling

The server provides detailed error messages with actionable suggestions:

Error Code

Meaning

Suggestion

MISSING_API_KEY

API key not configured

Set IRCAM_AMPLIFY_API_KEY environment variable

INVALID_API_KEY

API key rejected

Verify key at app.ircamamplify.io

INVALID_URL

Cannot access audio URL

Ensure URL is publicly accessible

UNSUPPORTED_FORMAT

Audio format not supported

Use MP3, WAV, FLAC, OGG, or M4A

FILE_TOO_LARGE

File exceeds 100MB limit

Use a shorter audio clip

RATE_LIMITED

Too many requests

Wait and retry

JOB_NOT_FOUND

Job ID invalid or expired

Job results expire after 24 hours

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Lint and format
npm run lint
npm run format

Architecture

src/
├── index.ts              # MCP server entry point
├── types/
│   ├── mcp-tools.ts      # MCP tool type definitions
│   └── ircam-api.ts      # IRCAM API response types
├── tools/
│   ├── analyze-music.ts  # Music tagging tool
│   ├── separate-stems.ts # Stem separation tool
│   ├── detect-ai-music.ts # AI detection tool
│   ├── analyze-loudness.ts # Loudness analysis tool
│   └── check-job-status.ts # Job polling tool
└── utils/
    ├── auth.ts           # API key management
    ├── http.ts           # HTTP client with retry
    ├── validation.ts     # Input validation
    └── errors.ts         # Error formatting

License

MIT - See LICENSE for details.

Support

Available Tools

5 tools
analyze_loudnessA

Analyze the loudness of an audio file following EBU R128 standard. Accepts a public URL to an audio file (MP3, WAV, FLAC, OGG, M4A). Returns integrated loudness (LUFS), true peak (dB), and loudness range (LU).

ParametersJSON Schema
NameRequiredDescriptionDefault
audio_urlYesPublic URL to the audio file to analyze

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adequately describes what the tool does (analyzes loudness) and what it returns (three specific metrics), but lacks information about potential limitations, error conditions, processing time, or authentication requirements. The description doesn't contradict any annotations since none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in two sentences: the first states the purpose and standard, the second specifies input requirements and output metrics. Every element serves a clear purpose with zero wasted words, making it easy to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no annotations and no output schema, the description provides good coverage of what the tool does, what it accepts, and what it returns. It could be more complete by addressing potential limitations or error scenarios, but given the tool's relative simplicity, it provides sufficient context for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100% with a single parameter clearly documented. The description adds valuable context by specifying supported file formats (MP3, WAV, FLAC, OGG, M4A) and clarifying that the URL must be public - information not present in the schema. This enhances understanding beyond the basic parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Analyze the loudness'), the target resource ('audio file'), and the technical standard ('EBU R128'). It distinguishes this tool from siblings like 'analyze_music' or 'detect_ai_music' by focusing specifically on loudness metrics rather than broader music analysis or AI detection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for audio loudness analysis following a specific standard, but does not explicitly state when to use this tool versus alternatives like 'analyze_music' or 'separate_stems'. It provides some context about supported file formats but lacks explicit guidance on when-not-to-use scenarios or clear alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

analyze_musicA

Analyze an audio file to extract genre, mood, tempo, key, and detected instruments. Accepts a public URL to an audio file (MP3, WAV, FLAC, OGG, M4A). Returns structured tags useful for music classification and discovery.

ParametersJSON Schema
NameRequiredDescriptionDefault
audio_urlYesPublic URL to the audio file to analyze

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the input format ('public URL to an audio file') and output purpose ('structured tags'), but lacks details on error handling, rate limits, or authentication needs, leaving gaps for a tool that performs analysis.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, uses two efficient sentences without redundancy, and every part contributes essential information, making it appropriately sized and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (analysis with one parameter) and no annotations or output schema, the description is adequate but incomplete. It covers input and output purpose but lacks details on response format, limitations, or error cases, which could hinder effective use by an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single parameter. The description adds value by specifying acceptable file formats ('MP3, WAV, FLAC, OGG, M4A') and clarifying the URL must be public, which goes beyond the schema's basic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('analyze an audio file') and resources involved ('extract genre, mood, tempo, key, and detected instruments'), distinguishing it from siblings like analyze_loudness or detect_ai_music by specifying comprehensive music analysis rather than focused tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('to extract genre, mood, tempo, key, and detected instruments' for 'music classification and discovery'), but does not explicitly state when not to use it or name alternatives among siblings, such as using analyze_loudness for volume analysis instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_job_statusA

Check the status of an async processing job. Use this to monitor jobs returned by separate_stems and other async operations. Returns job status (pending, processing, completed, failed), progress percentage, and results when completed.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesThe job ID returned by an async operation

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the tool's behavior by stating it returns job status, progress percentage, and results when completed, which is useful context. However, it lacks details on error handling, polling frequency, or timeouts, which are important for a monitoring tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose, usage, and return values without any wasted words. Every sentence earns its place by adding essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (monitoring async jobs), no annotations, and no output schema, the description is fairly complete—it explains what the tool does, when to use it, and what it returns. However, it could benefit from more behavioral details like error cases or response structure to fully compensate for the lack of structured data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the job_id parameter. The description adds minimal value by mentioning it's 'returned by an async operation,' but doesn't provide additional syntax or format details beyond what the schema implies, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verb ('check') and resource ('status of an async processing job'), and distinguishes it from siblings by mentioning it monitors jobs returned by 'separate_stems' and other async operations, which are different from analysis/detection tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool ('to monitor jobs returned by separate_stems and other async operations'), but does not explicitly state when not to use it or name specific alternatives for job monitoring, leaving some guidance gaps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

detect_ai_musicA

Detect whether an audio file was generated by AI or created by humans. Accepts a public URL to an audio file (MP3, WAV, FLAC, OGG, M4A). Returns a confidence score (0-100) and classification (ai_generated, human_made, or uncertain).

ParametersJSON Schema
NameRequiredDescriptionDefault
audio_urlYesPublic URL to the audio file to analyze

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses key behavioral traits: it analyzes audio files via URL, returns a confidence score and classification. However, it doesn't mention rate limits, authentication needs, error conditions, or processing time. The description doesn't contradict annotations (none exist).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the core purpose, the second specifies input requirements, and the third describes the return values. Every sentence adds essential information with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (classification task), no annotations, and no output schema, the description is fairly complete: it explains purpose, input requirements, and return values. However, it could benefit from more behavioral context (e.g., limitations, performance). The lack of output schema is partially compensated by describing return values in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the audio_url parameter fully. The description adds marginal value by reiterating 'public URL' and listing acceptable formats, but doesn't provide additional syntax or constraints beyond what the schema provides. Baseline 3 is appropriate when schema does heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verb ('detect') and resource ('audio file'), specifying what it detects ('generated by AI or created by humans'). It distinguishes itself from sibling tools like analyze_loudness or analyze_music by focusing on AI/human classification rather than audio analysis or processing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying acceptable file formats (MP3, WAV, FLAC, OGG, M4A) and that it accepts public URLs, but doesn't explicitly state when to use this tool versus alternatives like analyze_music or when not to use it (e.g., for non-audio files or private URLs). No explicit alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

separate_stemsA

Separate an audio file into individual stems: vocals, drums, bass, and other instruments. Accepts a public URL to an audio file (MP3, WAV, FLAC, OGG, M4A). For longer files, returns a job_id for async processing - use check_job_status to monitor progress.

ParametersJSON Schema
NameRequiredDescriptionDefault
audio_urlYesPublic URL to the audio file to separate

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool accepts public URLs for specific audio formats (MP3, WAV, FLAC, OGG, M4A), handles async processing for longer files by returning a job_id, and requires monitoring with 'check_job_status'. It does not cover aspects like rate limits, authentication needs, or error handling, but provides substantial operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by essential details about input format and async behavior. Every sentence adds critical information without redundancy, making it highly efficient and well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (audio processing with async capabilities), no annotations, and no output schema, the description does a good job of covering key aspects: purpose, input requirements, and async workflow. It lacks details on output format (e.g., what is returned for successful separation) and error conditions, but provides enough context for basic usage in conjunction with the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'audio_url' parameter fully documented in the schema. The description adds minimal value beyond the schema by reiterating that it accepts a public URL to an audio file, but does not provide additional semantics like URL format constraints or file size limits. The baseline score of 3 is appropriate given the schema's comprehensive coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('separate an audio file into individual stems') and lists the exact resources produced (vocals, drums, bass, and other instruments). It distinguishes this tool from sibling tools like 'analyze_loudness' or 'detect_ai_music' by focusing on audio separation rather than analysis or detection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (for separating audio stems from a public URL) and mentions an alternative action for longer files (using 'check_job_status' to monitor async processing). However, it does not explicitly state when NOT to use this tool or compare it to other sibling tools like 'analyze_music' for different audio processing needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedanalyze_loudness
    • First observedanalyze_music
    • First observedcheck_job_status
    • First observeddetect_ai_music
    • First observedseparate_stems
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: analyze_loudness focuses on loudness metrics, analyze_music on musical features, detect_ai_music on AI detection, separate_stems on audio separation, and check_job_status on job monitoring. The descriptions clearly differentiate their functions, eliminating any ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., analyze_loudness, check_job_status). This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions.

Tool Count5/5

With 5 tools, the server is well-scoped for audio analysis and processing. Each tool serves a specific, non-redundant function, and the count is appropriate for covering core operations without being overwhelming or insufficient.

Completeness4/5

The tool set covers key audio analysis tasks (loudness, music features, AI detection, stem separation) and includes job status checking for async operations. A minor gap is the lack of tools for audio editing or synthesis, but the provided tools support a complete workflow for analysis and processing within the stated domain.

Resources

Related MCP Connectors

Appeared in Searches