How to Use the Holded MCP in Mastra AI

Q: How do I connect the Holded MCP server to my Mastra AI agent?

After npm install @mastra/mcp, you'll instantiate a new MCPClient. In the client's configuration, you pass the unique server URL Vinkius provides for your Holded connection. Your Mastra AI agent can then access the tools.

Q: What's the best way to handle human approval for Holded invoices with Mastra AI?

Mastra AI includes a requireToolApproval option. You can design your workflow so that after an invoice is drafted using Holded tools, the agent pauses and waits for a human to approve the action before proceeding to send it.

Build resilient, automated business workflows for Holded. Mastra AI handles the retries and branching for you.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Holded MCP to Mastra AI

Create your Vinkius account to connect Holded 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 Holded with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate Your Invoicing Logic

Build workflows that do more than just send an invoice. Use `list_invoices` to find overdue payments, then use `get_contact_details` to find the right person to notify. Mastra AI's conditional logic lets you define what happens next: send a reminder, add a late fee, or flag the account for review. This isn't a simple script; it's a stateful workflow. The agent knows what it has already done and can make decisions based on the outcomes. This MCP server gives your agent the read/write access it needs to execute these complex tasks in Holded.

Make Inventory Syncs Bulletproof

Updating stock is a critical operation, and APIs aren't always available. When you use the `update_product_stock` tool inside a Mastra AI workflow, you get automatic retries with exponential backoff for free. If the Holded API is temporarily down or returns an error, your agent won't just fail. It will wait and try again, ensuring the stock update eventually succeeds. You can even add a step to call `get_api_profile` first as a pre-flight check to confirm your connection is healthy.

Build Custom Project Billing with Mastra AI

Create an agent that monitors your projects for billable events. The agent can periodically check `list_all_tasks` to see what work has been completed. Once a project milestone is met, it can use `get_project_details` to gather the details and generate a draft invoice in Holded. Because Mastra AI is built for workflows, you can insert a human approval step before the invoice is finalized. This gives you the speed of automation with the safety of manual oversight. The underlying MCP Server provides all the necessary tools for the job.

Setup guide

Set up Holded 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 Holded 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: "holded-mcp-client",
  servers: {
    "holded-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

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

const result = await agent.generate(
  "List recent Holded 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 Holded. 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 Holded 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 Holded MCP in Mastra AI

After `npm install @mastra/mcp`, you'll instantiate a new `MCPClient`. In the client's configuration, you pass the unique server URL Vinkius provides for your Holded connection. Your Mastra AI agent can then access the tools.

Yes, that's a core strength of Mastra AI. Any tool call, including `update_product_stock`, can be wrapped in a workflow step with a retry policy. Mastra AI will handle the backoff and re-attempts for you if the Holded API is temporarily unavailable.

Mastra AI includes a `requireToolApproval` option. You can design your workflow so that after an invoice is drafted using Holded tools, the agent pauses and waits for a human to approve the action before proceeding to send it.

Mastra AI uses the Holded MCP server to provide reliable access and adds its own layer of resilience. Its workflow engine can handle API errors, retry failed operations like `update_product_stock`, and run conditional logic to verify data with tools like `get_product_details` after an update.

Your project and task data is streamed from Holded to your Mastra AI agent through Vinkius's zero-trust infrastructure. The data is processed in-memory by your agent and is never logged or stored by the Vinkius MCP server. It's a direct, secure channel for your automations.

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