You.com MCP Server | Model Context Protocol Integration

Introduction

The You.com MCP Server brings comprehensive web search capabilities to your agentic IDE through the Model Context Protocol. Built with Bun runtime for optimal performance, it enables AI assistants to access real-time web results, news, and information directly within your development environment. Key Features:

🔍 Web and news search using You.com’s unified Search API
🚀 Multiple deployment options: Remote server (recommended) or local NPM package
🔒 Secure authentication with API keys
🎯 Advanced search operators: site filtering, file types, language filtering, exact terms
🌐 Support for multiple transport protocols (Stdio and HTTP)

Quick Start

Choose your deployment method:

Remote Server

Recommended - No installation required. Use the hosted server at https://api.you.com/mcp with your API key.

Local NPM Package

Install via npx @youdotcom-oss/mcp to run locally on your machine with stdio transport.

Prerequisites

Get a You.com API Key: Visit you.com/platform to obtain your API key
Choose your IDE: Select from Claude Code, Cursor, VS Code, JetBrains, Zed, or other supported editors

Standard Configuration Templates

Most MCP clients use one of these standard configuration formats: Remote Server (Recommended):

{
  "mcpServers": {
    "ydc-search": {
      "type": "http",
      "url": "https://api.you.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Local NPM Package:

{
  "mcpServers": {
    "ydc-search": {
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Replace <your-api-key> with your actual You.com API key from you.com/platform

Setup Guides

Windsurf

Setup:Use the standard configuration template in your Windsurf settings:

{
  "mcpServers": {
    "ydc-search": {
      "type": "http",
      "url": "https://api.you.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Windsurf MCP Documentation | Download Windsurf

Claude Code

Quick Setup (CLI):

# Add using Claude Code CLI
claude mcp add ydc-search npx @youdotcom-oss/mcp

Manual Setup - Remote Server (Recommended):Create or update .mcp.json in your workspace root:

{
  "mcpServers": {
    "ydc-search": {
      "type": "http",
      "url": "https://api.you.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Manual Setup - Local NPM Package:

{
  "mcpServers": {
    "ydc-search": {
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Replace <your-api-key> with your actual You.com API key from you.com/platform

Claude Desktop

Configuration:Add to your Claude Desktop MCP configuration file:Remote Server:

{
  "mcpServers": {
    "ydc-search": {
      "type": "http",
      "url": "https://api.you.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Local Package:

{
  "mcpServers": {
    "ydc-search": {
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Download Claude Desktop | MCP Setup Guide

Cursor IDE

GUI Setup (Easiest):

Open Cursor Settings → Features → MCP
Click ”+ Add New MCP Server”
For remote server:
- Select “Streamable HTTP” transport
- URL: https://api.you.com/mcp
- Add header: Authorization: Bearer <your-api-key>
For local package:
- Select “stdio” transport
- Command: npx
- Args: @youdotcom-oss/mcp
- Environment: YDC_API_KEY=<your-api-key>

Manual Setup:Create .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "ydc-search": {
      "url": "https://api.you.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

For Cursor, remove the "type" field from the configuration.

Cursor Documentation | Download Cursor

VS Code

Quick Setup (Command Line):

code --add-mcp '{"name":"ydc-search","command":"npx","args":["@youdotcom-oss/mcp"],"env":{"YDC_API_KEY":"<your-api-key>"}}'

Manual Setup:Create mcp.json in .vscode/mcp.json or your user profile:

{
  "servers": {
    "ydc-search": {
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Secure Setup with Input Prompts:For enhanced security, prompt for the API key at runtime:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ydc-api-key",
      "description": "You.com API Key",
      "password": true
    }
  ],
  "servers": {
    "ydc-search": {
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "${input:ydc-api-key}"
      }
    }
  }
}

Requirements: GitHub Copilot extension must be installed

VS Code MCP Documentation | Download VS Code

JetBrains IDEs

Configuration:Since JetBrains IDEs only support stdio transport, use mcp-remote to bridge HTTP to stdio:

{
  "mcpServers": {
    "ydc-search": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.you.com/mcp",
        "--header",
        "Authorization: Bearer ${YDC_API_KEY}"
      ],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Local Package Setup:

{
  "mcpServers": {
    "ydc-search": {
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Supported IDEs: IntelliJ IDEA, PyCharm, WebStorm, GoLand, RubyMine, PhpStorm, and more (requires AI Assistant enabled)JetBrains MCP Documentation

Zed Editor

Setup:Add to your Zed settings.json using "context_servers":Remote Server (using mcp-remote):

{
  "context_servers": {
    "ydc-search": {
      "source": "custom",
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.you.com/mcp",
        "--header",
        "Authorization: Bearer ${YDC_API_KEY}"
      ],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Local Package:

{
  "context_servers": {
    "ydc-search": {
      "source": "custom",
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Zed MCP Setup | Download Zed

Other Editors

Codex:Edit ~/.codex/config.toml:

[mcp_servers.ydc-search]
command = "npx"
args = ["@youdotcom-oss/mcp"]

[mcp_servers.ydc-search.env]
YDC_API_KEY = "<your-api-key>"

opencode:Edit ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ydc-search": {
      "type": "local",
      "command": ["npx", "@youdotcom-oss/mcp"],
      "enabled": true,
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Qodo Gen:

Open Qodo Gen chat panel in VSCode or IntelliJ
Click “Connect more tools” → ”+ Add new MCP”
Paste the standard configuration
Click Save

Qodo Gen DocumentationLM Studio:Edit mcp.json in LM Studio settings using the standard configuration template.Download LM StudioGemini CLI:Follow the MCP server setup guide using the standard configuration template.Goose:Go to “Advanced settings” → “Extensions” → “Add custom extension” and use the standard configuration template.Goose Installation Guide

Search Tool Reference

Using Natural Language: You don’t need to manually construct search queries with these parameters. Simply ask your AI assistant in natural language, and it will automatically use the tool schema to assemble the correct advanced query. For example, asking “What’s the latest news about the FCC on theverge.com” will automatically translate to a search with query: "What's the latest news about the FCC on theverge.com", site: "theverge.com", and freshness: "week".

you-search Tool

Performs comprehensive web and news search using the You.com Search API. The tool accepts natural language queries and supports advanced search parameters like site filtering, file types, language filtering, freshness, and more. For complete parameter details and response format, see the Search API Reference. Quick Examples: Natural language queries are automatically translated by your AI assistant:

“Latest machine learning tutorials on GitHub” → query: "machine learning tutorials", site: "github.com", freshness: "week"
“PDF files about Python” → query: "Python", fileType: "pdf"
“Spanish language articles about climate” → query: "climate", language: "es"

Advanced Configuration

Local Development Setup

For developers who want to contribute or customize the MCP server:

External Contributors: If you’re outside of You.com and want to contribute, visit the open-source repository to open pull requests or file issues.

Prerequisites:

Bun 1.2.21 or higher
You.com API key

Clone and Setup:

# Clone the repository
git clone https://github.com/youdotcom-oss/youdotcom-mcp-server.git
cd youdotcom-mcp-server

# Install dependencies
bun install

# Set up environment
echo "export YDC_API_KEY=<your-api-key>" > .env
source .env

Development Commands:

# Start server in stdio mode for development
bun run dev

# Build for production
bun run build

# Start HTTP server (default port 4000)
bun start

# Run tests
bun run test

# Run linting and formatting checks
bun run check

Local Integration with Claude Code:

{
  "mcpServers": {
    "ydc-search": {
      "type": "stdio",
      "command": "bun",
      "args": ["/full/path/to/youdotcom-mcp-server/src/stdio.ts"],
      "env": {
        "YDC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Docker Deployment

Deploy the MCP server using Docker for production environments:Build and Run:

# Build the optimized Docker image (243MB final size)
docker build -t youdotcom-mcp-server .

# Run the container
docker run -d -p 4000:4000 \
  -e YDC_API_KEY=<your-api-key> \
  --name youdotcom-mcp \
  youdotcom-mcp-server

Using Docker Compose:Create docker-compose.yml:

version: '3.8'
services:
  you-mcp-server:
    build: .
    ports:
      - "4000:4000"
    environment:
      - YDC_API_KEY=${YDC_API_KEY}
      - PORT=4000
    restart: unless-stopped

Run with:

docker-compose up -d

Configure Claude Code with Docker:

{
  "mcpServers": {
    "ydc-search": {
      "type": "http",
      "url": "http://localhost:4000/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Optimization Features:Multi-stage build with standalone binary compilation, minimal Ubuntu 22.04 base image (243MB final size), and runs as non-root user for enhanced security.

Transport Protocols

The MCP server supports two transport protocols:

HTTP Transport

Use for:

Remote server connections
Web applications
Production deployments

Authentication: Bearer token in headersEndpoint: https://api.you.com/mcp

Stdio Transport

Use for:

Local NPM package installations
Development environments
IDEs that only support stdio

Authentication: Environment variableCommand: npx @youdotcom-oss/mcp

Troubleshooting

API Key Issues

Symptoms: Authentication errors, “Invalid API key” messagesSolutions:

Verify your API key is active at you.com/platform
Check for extra spaces or quotes in your configuration
Ensure the API key has the correct scopes enabled
For environment variables, verify they’re properly exported

Connection Issues

Symptoms: “Connection refused”, timeout errorsSolutions:

Remote server: Check your internet connection and firewall settings
Local package: Ensure npx and Node.js are installed and in your PATH
Docker: Verify the container is running with docker ps
HTTP mode: Confirm the server is listening on the correct port

IDE Integration Issues

Symptoms: MCP server not appearing in IDE, tools not availableSolutions:

Restart your IDE after configuration changes
Check the IDE’s MCP logs for error messages
Verify the configuration file is in the correct location
For stdio transport, ensure the command is executable
Try the remote server option if local installation fails

Resources

NPM Package

Official package on npm

GitHub Repository

Source code and issues

MCP Specification

Model Context Protocol docs

Explore Further

Quickstart Guide

Get started with You.com API

Search API Reference

Detailed API documentation

Model Context Protocol

​Introduction

​Quick Start

Remote Server

Local NPM Package

​Prerequisites

​Standard Configuration Templates

​Setup Guides

​Search Tool Reference

​you-search Tool

​Advanced Configuration

​Transport Protocols

HTTP Transport

Stdio Transport

​Troubleshooting

​Resources

NPM Package

GitHub Repository

MCP Specification

​Explore Further

Quickstart Guide

Search API Reference

Introduction

Quick Start

Prerequisites

Standard Configuration Templates

Setup Guides

Search Tool Reference

you-search Tool

Advanced Configuration

Transport Protocols

Troubleshooting

Resources

Explore Further