How to Use the Namely MCP in Mastra AI

Q: How do I set up the Namely MCP server with a Mastra AI agent?

Install the @mastra/mcp package and instantiate a new MCPClient. You provide your Vinkius URL in the server configuration, then call mcpClient.listTools() and spread the result into your agent's toolset.

Q: Can my Mastra AI agent use Namely to check if an employee is in a specific department?

Yes. Your agent can call listgroups to get all department IDs, then use listprofiles with a groupid filter. Mastra's workflow engine lets you build this multi-step logic easily.

Q: Does Mastra AI's human-in-the-loop feature work with Namely tools?

Yes, it works perfectly. You can wrap any tool call, like getprofile, with requireToolApproval. This pauses the workflow and waits for a human to approve the action before the agent accesses the employee data from Namely.

Build resilient HR automation for Mastra AI that pulls employee data from Namely, with built-in retries and conditional logic.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Namely MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate New Hire Verification

Use this MCP server to build a Mastra AI workflow that checks if a new hire's profile is in Namely. Your agent calls `get_profile` with an email address. If it fails, Mastra's engine can automatically retry or escalate to an admin. You can chain this logic. If the profile is found, the agent then calls `get_team` to find their manager and trigger another action. It’s a reliable, hands-off process that you can set and forget.

Generate HR Reports on a Schedule

The `list_reports` tool lets your agent pull standard HR reports directly from Namely. You can build a Mastra AI workflow that runs this on the first of the month, then archives the report. This is way better than a simple cron job that just fails silently. You can add branching logic, so if `list_reports` returns an error, the agent notifies an admin instead of just stopping.

Sync Org Data for Your Mastra AI Agent

Your agent needs to know who's who. Use `list_profiles` and `list_teams` to periodically fetch the entire org structure from Namely and cache it for your Mastra AI agent. If the API call to the Namely MCP server times out, Mastra's built-in exponential backoff handles it gracefully. This ensures your sync job always completes, even if the network is flaky.

Setup guide

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

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

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

Install the `@mastra/mcp` package and instantiate a new `MCPClient`. You provide your Vinkius URL in the server configuration, then call `mcpClient.listTools()` and spread the result into your agent's toolset.

Yes. Your agent can call `list_groups` to get all department IDs, then use `list_profiles` with a `group_id` filter. Mastra's workflow engine lets you build this multi-step logic easily.

Create a scheduled workflow in Mastra AI that runs daily. It should call `list_profiles` and handle pagination to fetch all employees, then store the relevant fields. Use `requireToolApproval` for the initial setup to verify the data.

Yes, it works perfectly. You can wrap any tool call, like `get_profile`, with `requireToolApproval`. This pauses the workflow and waits for a human to approve the action before the agent accesses the employee data from Namely.

Data access is tightly controlled. First, your agent's connection to the MCP server is authenticated by a single token. Second, you can use Mastra's `requireToolApproval` feature to add a human checkpoint before your agent accesses sensitive employee profile details or organizational data.

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