How to Use the Nationalize MCP in Mastra AI

Build automated routing workflows with Mastra AI and name-origin predictions.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Nationalize MCP to Mastra AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate regional workflows with Mastra AI

The `predict_nationality` tool calculates the probability of a person's country of origin based on their surname. When you register this tool with your Mastra AI agent, you can build conditional branches that trigger different actions depending on the returned country code. If the Mastra AI agent detects a high probability of a European origin from the name, your workflow can automatically route the lead. If the Nationalize confidence score is too low, the Mastra AI workflow engine retries or escalates the task.

Bulletproof API retries for name lookups

The `predict_nationality` tool handles name parsing by talking directly to the Nationalize API. Mastra AI wraps this tool in its workflow engine, giving you automated exponential backoff if the external API experiences downtime. Your Mastra AI agent won't crash if the Nationalize network request drops. The Mastra AI framework handles the failure gracefully in the background, keeping your automated name-routing pipeline running smoothly.

Human-in-the-loop approval for this MCP Server

The `predict_nationality` tool works best when analyzing surnames, but some names return borderline confidence scores. Mastra AI allows you to set up a tool approval check before the agent acts on the prediction. This MCP Server integration stops the Mastra AI agent from making incorrect routing decisions when name accuracy is low. A team member can approve or override the predicted country code in Mastra AI before the workflow moves to the next step.

Setup guide

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

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

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

Install the Mastra MCP package, then initialize the client with your Vinkius server URL. Call the listTools function and spread the resulting tools directly into your Mastra agent configuration.

Yes, you can call the tool as a step in your Mastra AI workflow. Use the returned country code to branch your logic into different paths based on the predicted region.

Surnames carry much stronger regional signals than first names. Giving your Mastra AI agent the last name ensures the tool returns a highly accurate country prediction.

The Mastra client automatically detects the transport type, whether it is standard SSE or Streamable HTTP. It establishes the connection to the Vinkius sandbox without requiring custom network code.

The name string is sent directly to the Nationalize API to determine the origin. The connection is secure, and Vinkius runs the process in an isolated environment that discards the name data immediately after execution.

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