How to Use the Factorial MCP in Windsurf

Q: How do I connect the Factorial MCP Server to Windsurf?

Open your settings and add the server to your mcpconfig.json file under the mcpServers key. Once saved, the MCP panel will update, and Cascade will immediately discover all twelve HR tools.

Q: Can Windsurf automate clocking in and out of shifts in Factorial?

Yes. Cascade can run clockin and clockout directly when you start or finish your day. You can prompt it in plain English, and it will execute the action and confirm your status.

Q: How does Windsurf handle Factorial document searches?

Windsurf uses listdocuments and listfolders to search your company storage. It chains these calls to locate specific PDFs or spreadsheets, presenting them directly in your chat sidebar.

Get your HR operations handled inside Windsurf. Cascade chains Factorial tools to manage shifts and documents without manual clicking.

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

Autonomous Time and Shift Reconciliation in Windsurf

Cascade looks at your team's schedule and handles the tedious verification for you. When you ask it to check attendance, it runs `list_shifts` to fetch the current monthly schedules and compares them against actual clock-ins. If someone forgot to log their hours, Cascade doesn't just stop there. It automatically checks `list_leaves` to see if they were out on approved time off, then compiles a clean summary of missing logs.

Instant Team Directories and Employee Lookup

Stop leaving your editor to find a teammate's manager or department. Ask Windsurf to locate someone, and it uses `list_employees` to search the directory and `get_employee` to pull their full profile. It maps out organizational structures on the fly. Cascade can grab the entire company structure with `list_teams` and cross-reference it with `get_me` to show exactly where you fit in.

Direct Document and Folder Auditing

Finding HR paperwork is usually a pain, but this MCP Server changes that. Cascade searches your company vault using `list_folders` to locate the right directories and `list_documents` to pull up specific files. It can scan through years of payroll records by calling `list_payslips` to verify which documents are missing for the current quarter. You get the exact file paths without opening a browser.

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-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 settings and add the server to your `mcp_config.json` file under the `mcpServers` key. Once saved, the MCP panel will update, and Cascade will immediately discover all twelve HR tools.

Yes. Cascade can run `clock_in` and `clock_out` directly when you start or finish your day. You can prompt it in plain English, and it will execute the action and confirm your status.

Windsurf uses `list_documents` and `list_folders` to search your company storage. It chains these calls to locate specific PDFs or spreadsheets, presenting them directly in your chat sidebar.

You can ask Cascade to look up company-wide holidays. This MCP integration makes planning easy by calling `list_holidays` for the specified year and printing out the dates.

Your employee PII, payslips, and contract folders never touch external middleman servers. Vinkius runs the connector in a secure, isolated sandbox, meaning your raw Factorial API tokens and payroll data stay strictly between Windsurf and the platform's official endpoints.

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