How do I get a Hugging Face Access Token?

Log in to [**Hugging Face**](https://huggingface.co), go to **Settings > Access Tokens**, click **New token**, give it a name and select scopes (read is sufficient for browsing, write if you need to create repos). Copy the token immediately — it starts with `hf_`.

Can I search models by task type (e.g. text-generation)?

Yes! Use `list_models` with a search query. While the search endpoint doesn't directly filter by pipeline_tag, you can search by task name (e.g. search='text-generation') and then use `get_model` or `get_model_tags` to verify the pipeline_tag of specific models.

Can I see what files are in a model repository?

Yes! Use `list_model_files` with the model ID (e.g. 'google-bert/bert-base-uncased') to see the complete file tree including model weights (.safetensors, .bin), config files, tokenizer files and README. Optionally set a path to browse a specific subdirectory like 'onnx' or 'pytorch'.

Can I create discussions on model pages?

Yes! Use `create_discussion` with the repo type ('model', 'dataset' or 'space'), the repo ID and a title. This creates a new discussion thread on the repository. You can use `list_model_discussions` first to check existing threads before creating a new one.

Hugging Face MCP Server for Windsurf 13 tools — connect in under 2 minutes

Name: Hugging Face
Availability: InStock
Author: Vinkius

docs.windsurf.com/windsurf/mcp

Built by Vinkius GDPR 13 Tools IDE

Windsurf brings agentic AI coding to a purpose-built IDE. Connect Hugging Face through Vinkius and Cascade will auto-discover every tool. ask questions, generate code, and act on live data without leaving your editor.

Get MCP Server for AI Agents

ASK AI ABOUT THIS MCP SERVER

Open in ChatGPT Open in Claude Open in Perplexity

Vinkius supports streamable HTTP and SSE.

RecommendedModern Approach — Zero Configuration

Vinkius Desktop App

The modern way to manage MCP Servers — no config files, no terminal commands. Install Hugging Face and 2,500+ MCP Servers from a single visual interface.

Download Free Open SourceNo signup required

Classic Setup·json

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

Fully ManagedVinkius Servers

60%Token savings

High SecurityEnterprise-grade

IAMAccess control

EU AI ActCompliant

DLPData protection

V8 IsolateSandboxed

Ed25519Audit chain

<40msKill switch

Stream every event to Splunk, Datadog, or your own webhook in real-time

* Every MCP server runs on Vinkius-managed infrastructure inside AWS - a purpose-built runtime with per-request V8 isolates, Ed25519 signed audit chains, and sub-40ms cold starts optimized for native MCP execution. See our infrastructure

About Hugging Face MCP Server

Connect your Hugging Face account to any AI agent and explore the world's largest AI model hub through natural conversation.

Windsurf's Cascade agent chains multiple Hugging Face tool calls autonomously. query data, analyze results, and generate code in a single agentic session. Paste Vinkius Edge URL, reload, and all 13 tools are immediately available. Real-time tool feedback appears inline, so you see API responses directly in your editor.

What you can do

Model Discovery — Search and browse thousands of models by name, task type, framework and author
Model Inspection — View model metadata including pipeline task, tags, download counts, likes and file structure
Dataset Exploration — Find and inspect datasets with their descriptions, sizes and file trees
Spaces Gallery — Browse ML demo apps (Gradio, Streamlit, Docker) and check their runtime status
Collections — View curated collections of models, datasets and spaces organized by topic
Community Discussions — Read model discussion threads for bug reports, feature requests and usage tips
File Tree Browsing — List repository files (model weights, configs, tokenizers) without downloading

The Hugging Face MCP Server exposes 13 tools through the Vinkius. Connect it to Windsurf in under two minutes — no API keys to rotate, no infrastructure to provision, no vendor lock-in. Your configuration, your data, your control.

How to Connect Hugging Face to Windsurf via MCP

Follow these steps to integrate the Hugging Face MCP Server with Windsurf.

Open MCP Settings

Go to Settings → MCP Configuration or press Cmd+Shift+P and search "MCP"

Add the server

Paste the JSON configuration above into mcp_config.json

Save and reload

Windsurf will detect the new server automatically

Start using Hugging Face

Open Cascade and ask: "Using Hugging Face, help me...". 13 tools available

Why Use Windsurf with the Hugging Face MCP Server

Windsurf provides unique advantages when paired with Hugging Face through the Model Context Protocol.

Windsurf's Cascade agent autonomously chains multiple tool calls in sequence, solving complex multi-step tasks without manual intervention

Purpose-built for agentic workflows. Cascade understands context across your entire codebase and integrates MCP tools natively

JSON-based configuration means zero code changes: paste a URL, reload, and all 13 tools are immediately available

Real-time tool feedback is displayed inline, so you see API responses directly in your editor without switching contexts

Hugging Face + Windsurf Use Cases

Practical scenarios where Windsurf combined with the Hugging Face MCP Server delivers measurable value.

Automated code generation: ask Cascade to fetch data from Hugging Face and generate models, types, or handlers based on real API responses

Live debugging: query Hugging Face tools mid-session to inspect production data while debugging without leaving the editor

Documentation generation: pull schema information from Hugging Face and have Cascade generate comprehensive API docs automatically

Rapid prototyping: combine Hugging Face data with Cascade's code generation to scaffold entire features in minutes

Hugging Face MCP Tools for Windsurf (13)

These 13 tools become available when you connect Hugging Face to Windsurf via MCP:

create_discussion

Requires the repo type (model, dataset or space), the repo ID in "author/name" format and the discussion title. Returns the created discussion with its ID, title and URL. Create a new discussion on a Hugging Face repo

get_collection

Provide the collection slug. Get details for a specific Hugging Face collection

get_model

Provide the model ID in "author/name" format (e.g. "google-bert/bert-base-uncased"). Get details for a specific Hugging Face model

get_model_tags

Tags include framework (pytorch, tensorflow), license, dataset, language and task-specific labels. The pipeline_tag indicates the model's primary task (e.g. "text-generation", "image-classification", "translation"). Get tags and pipeline info for a Hugging Face model

get_space

Provide the space ID in "author/name" format. Get details for a specific Hugging Face Space

get_user

Returns user name, avatar, organizations, auth type, plan and access tokens metadata. Use this to verify your token is working correctly. Get the authenticated Hugging Face user

list_collections

Optionally filter by author and limit. Returns collection slug, title, description, author, item count and likes count. List collections on Hugging Face Hub

list_dataset_files

Returns filenames (e.g. "train.parquet", "test.parquet", "data/", "README.md"). Optionally set a subdirectory path. Useful for understanding dataset structure before downloading. List files in a Hugging Face dataset repository

list_datasets

Optionally filter by search term, author and limit. Returns dataset ID, author, description, download count, likes count and creation date. List datasets on Hugging Face Hub

list_model_discussions

Returns discussion title, author, creation date, number of comments and whether it is resolved. Use this to review community feedback, bug reports and feature requests for a model. List discussions for a Hugging Face model

list_model_files

Returns filenames, file sizes and paths (e.g. "model.safetensors", "tokenizer.json", "config.json", "README.md"). Optionally set a subdirectory path to list files within a specific folder. Useful for inspecting model artifacts and understanding the repository structure. List files in a Hugging Face model repository

list_models

Optionally filter by search term (free-text across model cards), author (organization or username) and limit the number of results. Returns model ID, author, pipeline task tag, download count, likes count and creation date. List models on Hugging Face Hub

list_spaces

Optionally filter by search term, author and limit. Returns space ID, title, author, SDK (Gradio, Streamlit, Docker), likes count and creation date. List Spaces on Hugging Face Hub

Example Prompts for Hugging Face in Windsurf

Ready-to-use prompts you can give your Windsurf agent to start working with Hugging Face immediately.

"Find popular text generation models with over 1000 likes."

"Show me what files are in the bert-base-uncased model."

"What discussions are happening on the Llama-3 model page?"

Troubleshooting Hugging Face MCP Server with Windsurf

Common issues when connecting Hugging Face to Windsurf through the Vinkius, and how to resolve them.

Server not connecting

Check Settings → MCP for the server status. Try toggling it off and on.

Hugging Face + Windsurf FAQ

Common questions about integrating Hugging Face MCP Server with Windsurf.

How does Windsurf discover MCP tools?

Windsurf reads the mcp_config.json file on startup and connects to each configured server via Streamable HTTP. Tools are listed in the MCP panel and available to Cascade automatically.

Can Cascade chain multiple MCP tool calls?

Yes. Cascade is an agentic system. it can plan and execute multi-step workflows, calling several tools in sequence to accomplish complex tasks without manual prompting between steps.

Does Windsurf support multiple MCP servers?

Yes. Add as many servers as needed in mcp_config.json. Each server's tools appear in the MCP panel and Cascade can use tools from different servers in a single flow.