How to Use the Musixmatch MCP in Mastra AI

Q: How do I register Musixmatch tools inside a Mastra AI agent?

Install @mastra/mcp@latest and initialize the MCP client with your Vinkius endpoint. You can then list the tools and spread them directly into your agent's tool array.

Q: Can I require manual approval before Mastra AI fetches lyrics?

Yes, you can set requireToolApproval on the gettracklyrics tool. This forces the agent to wait for human confirmation before making the API call.

Q: How do I fetch the top tracks in a specific order?

Use the gettoptracks tool inside your workflow step. You can write custom TypeScript logic in your Mastra step to sort or filter the resulting array of songs.

Q: Is my artist metadata search query kept private?

Yes. All queries sent to getartistdetails run through Vinkius's zero-trust sandbox. The metadata fetched is returned directly to your agent, and no search history is retained on our servers.

Build resilient music workflows with Mastra AI and the Musixmatch MCP.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Musixmatch MCP to Mastra AI

Create your Vinkius account to connect Musixmatch to Mastra AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Musixmatch with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate playlist curation with Mastra AI

The Musixmatch MCP server exposes `get_top_tracks` to fetch the current global charts. You can configure a Mastra workflow that runs every morning, grabs the top hits, and filters them based on specific artist criteria. The built-in workflow engine lets you write conditional logic to skip tracks that don't match your criteria. If the initial fetch fails, Mastra automatically retries the call with exponential backoff. This ensures your automated music curation pipeline doesn't break over a temporary network hiccup.

Verify and clean song matches with workflows

The `match_track_lyrics` tool lets your agent find a song based on a few words. With Mastra, you can build a multi-step verification pipeline that takes the matched ID and passes it to `get_track_details` to verify the genre and release date before saving it. If the match confidence is low, you can trigger a human-in-the-loop approval step. Mastra pauses the execution, asks you for confirmation in Slack, and resumes only when you approve the track.

Extract entire artist discographies reliably

The `search_artists` tool finds the unique identifier for any musician. Once found, your agent uses `get_artist_albums` to pull every album they have ever released. This is perfect for building deep-dive databases or analysis tools. Because discographies can be massive, Mastra handles the rate limits of the API by queuing the calls. It processes each album systematically without triggering blocklists.

Setup guide

Set up Musixmatch MCP in Mastra AI

Prerequisites

Node.js 18+ and a TypeScript project
@mastra/mcp + @mastra/core packages
Active Vinkius subscription with a valid endpoint token

1

Install dependencies
Run npm install @mastra/mcp @mastra/core plus your preferred model provider (e.g. @ai-sdk/openai).
2

Configure the MCPClient
Create an MCPClient with your Vinkius endpoint as a URL object. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.
3

Discover and inject tools
Call mcpClient.listTools() and spread the result into your agent's tools object. All Musixmatch tools become native Mastra tools.
4

Run with any model
Swap openai("gpt-4o") for any AI SDK-compatible provider. Call agent.generate() and the agent routes tool calls through MCP automatically.

agent.ts

import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const mcpClient = new MCPClient({
  id: "musixmatch-mcp-client",
  servers: {
    "musixmatch-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

const agent = new Agent({
  name: "Musixmatch Agent",
  model: openai("gpt-4o"),
  instructions: "You have access to Musixmatch tools.",
  tools: {
    ...(await mcpClient.listTools()),
  },
});

const result = await agent.generate(
  "List recent Musixmatch transactions"
);
console.log(result.text);

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Musixmatch. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Musixmatch now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Musixmatch MCP in Mastra AI

Install `@mastra/mcp@latest` and initialize the MCP client with your Vinkius endpoint. You can then list the tools and spread them directly into your agent's tool array.

Yes, Mastra has built-in retry logic. If an MCP tool call like `get_track_lyrics` returns a rate limit error, Mastra backsoff and retries the request automatically.

Yes, you can set `requireToolApproval` on the `get_track_lyrics` tool. This forces the agent to wait for human confirmation before making the API call.

Use the `get_top_tracks` tool inside your workflow step. You can write custom TypeScript logic in your Mastra step to sort or filter the resulting array of songs.

Yes. All queries sent to `get_artist_details` run through Vinkius's zero-trust sandbox. The metadata fetched is returned directly to your agent, and no search history is retained on our servers.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript