How to Use the Sensible MCP in Windsurf

Q: How does Windsurf use the Sensible MCP to parse raw PDFs?

Windsurf sends your local PDFs or URLs to the server using extractfromurl or extractsync. Cascade reads the returned JSON structure directly, allowing it to write code or update databases using the extracted fields.

Q: Can Cascade handle unrecognized documents with Sensible on Windsurf?

Yes, Cascade uses classifysync to check the file type first. If the file is unrecognized, Cascade can create a new target schema using createdocumenttype and upload a reference file using creategolden.

Q: How do I refresh my Sensible configurations inside the Windsurf workspace?

You run listconfigurations to see active layouts, and Cascade updates them using updateconfiguration. Once modified, Cascade executes publishconfiguration so your next extraction uses the updated rules.

Q: What happens if my extraction payload is too large for a direct sync call?

Cascade switches to asynchronous mode by running generateuploadurl on this MCP Server. It uploads the file, polls the status using getdocument, and processes the final JSON once the extraction completes.

Throw your messy PDFs at Windsurf and watch Cascade extract clean JSON without you writing a single line of custom parsing code.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect Sensible MCP to Windsurf

Create your Vinkius account to connect Sensible to Windsurf — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup Sensible with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Multi-step document classification with Windsurf Cascade

The `classify_sync` tool sniffs out the exact layout of your incoming files instantly. Cascade uses this classification to figure out which parser configuration to run next, handling the whole check in one autonomous pass. When a document fails immediate sorting, Windsurf fires off `classify_async` in the background. Cascade watches the job, updates your workspace, and keeps things moving while you focus on actual coding.

Automated parser configuration and publishing

The `create_configuration` tool sets up new document schemas directly from your Windsurf editor. Cascade uses this MCP Server to write the schema layout, run tests against your sample files, and update the definition without you leaving your active file. Once your schema matches the target layouts, Cascade calls `publish_configuration` to push the changes live. It manages the entire lifecycle, including cleanup tasks with `delete_configuration` if you need to discard draft layouts during testing.

Turning raw document extractions into clean spreadsheets

The `generate_csv` tool compiles raw JSON output from past extractions into organized spreadsheets. When you ask Cascade to build a summary of recent uploads, it queries the backend, pulls the JSON, and writes a physical CSV file to your workspace. For more complex data structures, Cascade invokes `generate_excel` to build multi-sheet workbooks. It chains this with `list_extractions` to pull historical data, ensuring your spreadsheets contain exactly the records you asked for.

Setup guide

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

mcp_config.json

{
  "mcpServers": {
    "sensible-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 Sensible. 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 Sensible 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 Sensible MCP in Windsurf

Windsurf sends your local PDFs or URLs to the server using `extract_from_url` or `extract_sync`. Cascade reads the returned JSON structure directly, allowing it to write code or update databases using the extracted fields.

Yes, Cascade uses `classify_sync` to check the file type first. If the file is unrecognized, Cascade can create a new target schema using `create_document_type` and upload a reference file using `create_golden`.

You run `list_configurations` to see active layouts, and Cascade updates them using `update_configuration`. Once modified, Cascade executes `publish_configuration` so your next extraction uses the updated rules.

Cascade switches to asynchronous mode by running `generate_upload_url` on this MCP Server. It uploads the file, polls the status using `get_document`, and processes the final JSON once the extraction completes.

Your PDFs and images are processed in Vinkius's secure sandbox before hitting the Sensible MCP Server parsing engine. The resulting JSON extractions are sent directly back to Windsurf, and no raw document data is stored on Vinkius servers after the execution context closes.

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