How to Use the Factorial MCP in Mastra AI

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

Initialize the MCPClient with your Vinkius server URL. Call mcpClient.listTools() and spread the resulting tools array directly into your Mastra agent's tool configuration.

Q: Can Mastra AI handle multi-step Factorial updates automatically?

Yes. You can build a workflow that first calls listemployees, filters the results, and then sequentially queries listpayslips for each active team member in parallel.

Q: How do I set up human-in-the-loop approvals for Factorial actions in Mastra AI?

Use the requireToolApproval option in your Mastra configuration. This pauses execution and prompts an admin before the agent can trigger sensitive tools like clockin or document access.

Build resilient HR workflows with Mastra AI and the Factorial MCP Server.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Factorial MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automated leave and holiday workflows with Mastra AI

The `list_leaves` tool retrieves all pending time-off requests for the current year. Mastra AI processes these requests through structured workflows, automatically comparing them against company holidays retrieved via `list_holidays`. If a conflict occurs, the workflow branches immediately to alert the manager. You define these rules in pure TypeScript, letting the framework handle retries if the external API experiences temporary downtime.

Self-healing employee onboarding pipelines

The `get_me` tool verifies the active company identity before triggering downstream actions. From there, the agent uses `list_teams` to identify where a new hire belongs and pulls their profile using `get_employee`. Mastra handles API failures gracefully with built-in exponential backoff. If a network blip occurs during an MCP team lookup, the system retries the call automatically without crashing your main application.

Programmatic payroll and document checks

The `list_payslips` tool grabs payment records for specific months to audit active runs. The agent queries the MCP Server to cross-reference these records against active shifts pulled from `list_shifts` to spot discrepancies. You can require manual approval before any data is exported or modified. This keeps a human in the loop for sensitive payroll tasks while automating the heavy lifting of data gathering.

Setup guide

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

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

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

Initialize the `MCPClient` with your Vinkius server URL. Call `mcpClient.listTools()` and spread the resulting tools array directly into your Mastra agent's tool configuration.

Yes. You can build a workflow that first calls `list_employees`, filters the results, and then sequentially queries `list_payslips` for each active team member in parallel.

Use the `requireToolApproval` option in your Mastra configuration. This pauses execution and prompts an admin before the agent can trigger sensitive tools like `clock_in` or document access.

The client automatically negotiates the transport protocol. It defaults to SSE or Streamable HTTP depending on your hosting environment, ensuring low-latency communication with the server.

All time-tracking entries, shift logs, and internal documents remain strictly within your private network boundary. Vinkius processes these requests inside ephemeral, zero-trust sandboxes that destroy execution state the moment the tool call completes.

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