How to Connect Hugging Face Remote MCP to Windsurf
Add Hugging Face's remote MCP server to Windsurf in about a minute.
Step-by-step
- Edit mcp_config.jsonAdd the
serverUrlconfig above to~/.codeium/windsurf/mcp_config.jsonand refresh in Cascade. - AuthorizeAdd an
Authorization: Bearer <your-key>header in the server's config โ get the credential from https://huggingface.co/docs/hub/en/hf-mcp-server. - VerifyVerify in the browser: paste
https://huggingface.co/mcpinto remotemcp.net/inspector and run initialize + tools/list.
Troubleshooting OAuth / 401
- A
401 Unauthorizedon first connect is normal โ the endpoint is OAuth-protected; let Windsurf finish the browser consent flow. - If the consent window never opens, remove and re-add the server, then retry.
- Check the exact challenge at our OAuth debugger.
- Run the live endpoint through the online inspector to see the raw JSON-RPC exchange.
Or add to ~/.cursor/mcp.json:
{
"mcpServers": {
"huggingface": {
"url": "https://huggingface.co/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}claude mcp add --transport http huggingface https://huggingface.co/mcp
With credential header:
claude mcp add --transport http huggingface https://huggingface.co/mcp --header "Authorization: Bearer YOUR_API_KEY"
Or add to .vscode/mcp.json:
{
"servers": {
"huggingface": {
"type": "http",
"url": "https://huggingface.co/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}- Open Settings โ Connectors (Integrations) โ Add Custom Connector.
- Paste the endpoint URL:
https://huggingface.co/mcp - Provide your API key / Bearer token when prompted.
Bridge the remote endpoint into stdio with mcp-remote in claude_desktop_config.json:
{
"mcpServers": {
"huggingface": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://huggingface.co/mcp",
"--header",
"Authorization: Bearer YOUR_API_KEY"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"huggingface": {
"serverUrl": "https://huggingface.co/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Tools exposed by Hugging Face MCP (4)
| Tool | Safety | Description | Parameters |
|---|---|---|---|
| search_models | ๐ข Read | Search Hugging Face Hub models by name, task or filter. | query*: stringlimit: number |
| search_datasets | ๐ข Read | Search Hugging Face Hub datasets. | query*: stringlimit: number |
| search_spaces | ๐ข Read | Search Hugging Face Spaces (interactive ML demos). | query*: stringlimit: number |
| get_paper_details | ๐ข Read | Get details for a paper on Hugging Face Papers. | arxivId*: string |
Connect Hugging Face MCP to another client
Other servers for Windsurf
GitHub's official remote MCP server hosted at api.githubcopilot.com. Gives AI agents first-party access to repositories, issues, pull requests and code search.
Notion's official hosted MCP server. Agents can search your workspace, read and create pages, and query databases over Streamable HTTP or SSE.
Linear's official remote MCP server. Agents can search, create and update issues and query your team's workflow over Streamable HTTP or SSE.
Figma's official remote MCP server. Agents can pull design context, variables, Code Connect mappings and screenshots from your Figma files.
Stripe's official remote MCP server at mcp.stripe.com. Agents can query customers, payment intents and subscriptions and invoke Stripe API operations with OAuth.
Cloudflare's free, authless documentation MCP server. Agents can search the full Cloudflare docs corpus โ no account or token required.