How to Use the Humaans MCP in Mastra AI

Q: How do I register Humaans tools in a Mastra AI agent?

Instantiate the client using new MCPClient with your Vinkius URL. Then, call listTools() to retrieve the Humaans tools and pass them directly to your agent's tool array.

Q: How do I require human approval for Humaans document access in Mastra AI?

You use the requireToolApproval configuration in Mastra AI when defining the agent. This halts execution whenever the agent attempts to call listdocuments, requiring manual admin sign-off.

Q: How does the agent fetch my personal profile?

The agent invokes getme through the server connection. This returns your authenticated Humaans profile, allowing the agent to personalize its responses based on your role.

Automate complex Humaans HR workflows with Mastra AI's conditional routing and agent retry engines.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Humaans MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automated Leave Escalations

The `list_leaves` and `get_employee` tools allow your Mastra AI agent to monitor Humaans time-off requests and match them against employee profiles. If a critical team member requests leave during a launch week, the Mastra AI workflow engine triggers conditional branches to notify managers. You register these Humaans tools using `mcpClient.listTools()` and spread them directly into your Mastra AI agent definition. Rate limit spikes are handled automatically by Mastra AI, retrying the call with exponential backoff so your automated HR flows never drop a request.

Secure Document Auditing via Mastra AI

The `list_documents` tool lets your Mastra AI agent audit company compliance records inside Humaans systematically. Mastra AI coordinates the search across Humaans employee folders, checking for missing contracts or expired identification files. To keep sensitive Humaans HR files secure, you can set `requireToolApproval` on this MCP Server tool. This pauses the Mastra AI workflow and alerts an HR admin to approve the document access before the agent can read the file contents.

Dynamic Role and Team Provisioning

The `list_roles`, `list_teams`, and `list_departments` tools fetch your current Humaans organizational structures to sync downstream systems. When a department changes, your Mastra AI agent detects the shift in Humaans and updates your internal directories. Because this MCP Server integrates directly with Mastra AI, you can deploy your sync workflows to any cloud with a single command. Your automated agent uses these Humaans tools to keep engineering teams and roles perfectly aligned with your HR source of truth.

Setup guide

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

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

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

Instantiate the client using `new MCPClient` with your Vinkius URL. Then, call `listTools()` to retrieve the Humaans tools and pass them directly to your agent's tool array.

Yes, Mastra AI's built-in workflow engine handles transient network errors and rate limits on this MCP Server. It automatically retries calls to endpoints like `list_employees` using exponential backoff.

You use the `requireToolApproval` configuration in Mastra AI when defining the agent. This halts execution whenever the agent attempts to call `list_documents`, requiring manual admin sign-off.

The agent invokes `get_me` through the server connection. This returns your authenticated Humaans profile, allowing the agent to personalize its responses based on your role.

Your employee leave records and profile details are never cached on the MCP gateway. Vinkius executes the connector inside isolated, ephemeral containers, ensuring your HRIS payloads stream directly to your Mastra agent over TLS 1.3 without leaving any persistent footprint.

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