How to Use the Namely MCP in Windsurf

Q: Can Windsurf query specific teams using Namely?

Yes, Cascade uses getteam and listteams to filter profiles by department. It chains these commands in Windsurf to isolate specific teams without manual intervention.

Q: How does the Namely MCP Server handle custom fields in Windsurf?

The server exposes the listfields tool directly to Cascade. Windsurf reads these custom definitions and applies them when querying listprofiles so your custom HR data isn't lost.

Q: Can I run bulk employee searches using Namely tools in Windsurf?

Yes. Cascade calls listprofiles to fetch the complete Namely directory into your Windsurf terminal. It can then run getprofile on specific matches if you need deeper details on a single employee.

Get your HRIS data directly inside Windsurf so Cascade can build org charts and track anniversaries on autopilot.

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 Windsurf

Create your Vinkius account to connect Namely to Windsurf 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 Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate Org Chart Construction

Cascade doesn't just look up one person at a time. It chains calls to Namely's MCP tools like `list_profiles` and `get_team` to build a complete picture of your reporting lines. You tell Cascade to find who reports to whom, and it maps the entire department structure in Windsurf in one go. By querying `list_groups` alongside these Namely profiles, Cascade groups employees by department or office location. You get an accurate org visual in Windsurf without manually parsing nested JSON payloads or clicking through the browser UI.

Track Anniversaries and Team Events in Windsurf

Keep your team connected without leaving your Windsurf workspace. Cascade uses the Namely MCP Server to scan your organization timeline by running `list_events`. It checks for upcoming birthdays and work milestones, presenting them directly in your Cascade panel. If you need to announce these milestones, Cascade can pull company announcements via `list_announcements`. It links historical Namely announcements with current events, letting you draft team updates in Windsurf that match your company's actual timeline.

Map Custom Fields for Tailored Reporting

Every Namely setup has its own weird custom fields that standard integrations miss. Cascade solves this by invoking `list_fields` to inspect your specific setup, then running `list_reports` to pull the precise metrics you need. It matches these custom Namely fields against active roles retrieved from `list_jobs`. Cascade handles the mapping behind the scenes, giving you clean data in Windsurf without requiring custom scripting on your end.

Setup guide

Set up Namely MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the Namely MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my Namely payment history." If connected, Cascade will call the Namely tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "namely-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

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 Windsurf

Cascade connects directly to Namely via our MCP Server to pull raw data. It runs `list_reports` and formats the output inside Windsurf without you having to write custom API clients.

Yes, Cascade uses `get_team` and `list_teams` to filter profiles by department. It chains these commands in Windsurf to isolate specific teams without manual intervention.

The server exposes the `list_fields` tool directly to Cascade. Windsurf reads these custom definitions and applies them when querying `list_profiles` so your custom HR data isn't lost.

Yes. Cascade calls `list_profiles` to fetch the complete Namely directory into your Windsurf terminal. It can then run `get_profile` on specific matches if you need deeper details on a single employee.

Your Namely PII, including employee profiles and job details, remains local. Windsurf communicates with the Namely API using an ephemeral V8 sandbox that handles authentication securely and never stores your credentials on our servers.

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