How to Use the Factorial MCP in Windsurf

Q: How do I configure the Factorial MCP Server inside Windsurf?

Open your /.codeium/windsurf/mcpconfig.json file and add the server configuration under the mcpServers key. Alternatively, use the Windsurf Settings UI under Cascade to add the endpoint, then refresh Cascade to discover the MCP tools.

Q: Can Windsurf edit employee profiles in Factorial?

No, it cannot. The getemployeedetails tool only allows Cascade to read existing profile data and roles. This read-only setup prevents your Windsurf agent from accidentally modifying employee records or changing job titles.

Q: How does Windsurf handle large lists of active employees in Factorial?

When Cascade calls listemployees to search your Factorial directory, it retrieves basic metadata like names and email addresses. If your team is massive, Cascade processes the JSON output in chunks to keep your Windsurf context window clean.

Run complex, multi-step HR workflows autonomously in Windsurf by letting Cascade query your Factorial directory.

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 Windsurf

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Audit contracts and teams automatically in Windsurf

The `list_employee_contracts` tool pulls active employment agreements directly into your Cascade context window. Cascade can immediately compare these agreements against the team structures retrieved by `list_company_teams` to spot misaligned departments or expired agreements. You don't have to trigger these steps one by one. Our integration chains these queries automatically, looking up team memberships and cross-referencing contract dates without waiting for your next prompt.

Reconcile shifts with leave requests in Cascade

The `list_attendance_shifts` tool lets Cascade scan clock-in records to find discrepancies in your payroll data. By combining this with `list_time_off_leaves`, your Windsurf agent spots instances where employees logged hours while officially on approved leave. Cascade handles the entire lookup loop on its own. It pulls the records, compares the timestamps, and flags the exact dates that require manual correction by your HR team.

Map your HR document library using this MCP Server

The `list_document_folders` tool exposes your entire Factorial file structure directly to your IDE. This MCP Server lets Cascade browse through corporate policies and employee handbooks without leaving your active workspace. Once Cascade finds the correct folder, it calls `list_hr_documents` to locate specific forms or compliance files. You get a clean list of document IDs and metadata right inside your Windsurf terminal.

Setup guide

Set up Factorial 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 Factorial 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 Factorial payment history." If connected, Cascade will call the Factorial tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "factorial-alternative-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 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 Windsurf

Open your `~/.codeium/windsurf/mcp_config.json` file and add the server configuration under the `mcpServers` key. Alternatively, use the Windsurf Settings UI under Cascade to add the endpoint, then refresh Cascade to discover the MCP tools.

No, it cannot. The `get_employee_details` tool only allows Cascade to read existing profile data and roles. This read-only setup prevents your Windsurf agent from accidentally modifying employee records or changing job titles.

When Cascade calls `list_employees` to search your Factorial directory, it retrieves basic metadata like names and email addresses. If your team is massive, Cascade processes the JSON output in chunks to keep your Windsurf context window clean.

You do not. Windsurf relies on the MCP integration to chain tools like `list_employees` and `get_employee_details` together. You just ask Cascade to find a specific person's manager, and it executes the sequence autonomously.

Yes, your employee contracts and attendance shifts remain secure because Vinkius runs the server in an ephemeral, zero-trust sandbox. Windsurf only receives the specific data payloads requested by Cascade, and your API keys never leave the secure environment.

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