Developer Resources

MCP Server

Dev

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

  1. Get a You.com API Key: Visit you.com/platform to obtain your API key
  2. 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):

1{
2  "mcpServers": {
3    "ydc-search": {
4      "type": "http",
5      "url": "https://api.you.com/mcp",
6      "headers": {
7        "Authorization": "Bearer <your-api-key>"
8      }
9    }
10  }
11}

Local NPM Package:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "command": "npx",
5      "args": ["@youdotcom-oss/mcp"],
6      "env": {
7        "YDC_API_KEY": "<your-api-key>"
8      }
9    }
10  }
11}
Replace <your-api-key> with your actual You.com API key from you.com/platform

Setup Guides

Setup:

Use the standard configuration template in your Windsurf settings:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "type": "http",
5      "url": "https://api.you.com/mcp",
6      "headers": {
7        "Authorization": "Bearer <your-api-key>"
8      }
9    }
10  }
11}

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:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "type": "http",
5      "url": "https://api.you.com/mcp",
6      "headers": {
7        "Authorization": "Bearer <your-api-key>"
8      }
9    }
10  }
11}

Manual Setup - Local NPM Package:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "command": "npx",
5      "args": ["@youdotcom-oss/mcp"],
6      "env": {
7        "YDC_API_KEY": "<your-api-key>"
8      }
9    }
10  }
11}
Replace <your-api-key> with your actual You.com API key from you.com/platform

Configuration:

Add to your Claude Desktop MCP configuration file:

Remote Server:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "type": "http",
5      "url": "https://api.you.com/mcp",
6      "headers": {
7        "Authorization": "Bearer <your-api-key>"
8      }
9    }
10  }
11}

Local Package:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "command": "npx",
5      "args": ["@youdotcom-oss/mcp"],
6      "env": {
7        "YDC_API_KEY": "<your-api-key>"
8      }
9    }
10  }
11}

Download Claude Desktop | MCP Setup Guide

GUI Setup (Easiest):

  1. Open Cursor Settings → Features → MCP
  2. Click ”+ Add New MCP Server”
  3. For remote server:
    • Select “Streamable HTTP” transport
    • URL: https://api.you.com/mcp
    • Add header: Authorization: Bearer <your-api-key>
  4. 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:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "url": "https://api.you.com/mcp",
5      "headers": {
6        "Authorization": "Bearer <your-api-key>"
7      }
8    }
9  }
10}
For Cursor, remove the "type" field from the configuration.

Cursor Documentation | Download Cursor

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:

1{
2  "servers": {
3    "ydc-search": {
4      "command": "npx",
5      "args": ["@youdotcom-oss/mcp"],
6      "env": {
7        "YDC_API_KEY": "<your-api-key>"
8      }
9    }
10  }
11}

Secure Setup with Input Prompts:

For enhanced security, prompt for the API key at runtime:

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "ydc-api-key",
6      "description": "You.com API Key",
7      "password": true
8    }
9  ],
10  "servers": {
11    "ydc-search": {
12      "command": "npx",
13      "args": ["@youdotcom-oss/mcp"],
14      "env": {
15        "YDC_API_KEY": "${input:ydc-api-key}"
16      }
17    }
18  }
19}
Requirements: GitHub Copilot extension must be installed

VS Code MCP Documentation | Download VS Code

Configuration:

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

1{
2  "mcpServers": {
3    "ydc-search": {
4      "command": "npx",
5      "args": [
6        "mcp-remote",
7        "https://api.you.com/mcp",
8        "--header",
9        "Authorization: Bearer ${YDC_API_KEY}"
10      ],
11      "env": {
12        "YDC_API_KEY": "<your-api-key>"
13      }
14    }
15  }
16}

Local Package Setup:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "command": "npx",
5      "args": ["@youdotcom-oss/mcp"],
6      "env": {
7        "YDC_API_KEY": "<your-api-key>"
8      }
9    }
10  }
11}

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

JetBrains MCP Documentation

Setup:

Add to your Zed settings.json using "context_servers":

Remote Server (using mcp-remote):

1{
2  "context_servers": {
3    "ydc-search": {
4      "source": "custom",
5      "command": "npx",
6      "args": [
7        "mcp-remote",
8        "https://api.you.com/mcp",
9        "--header",
10        "Authorization: Bearer ${YDC_API_KEY}"
11      ],
12      "env": {
13        "YDC_API_KEY": "<your-api-key>"
14      }
15    }
16  }
17}

Local Package:

1{
2  "context_servers": {
3    "ydc-search": {
4      "source": "custom",
5      "command": "npx",
6      "args": ["@youdotcom-oss/mcp"],
7      "env": {
8        "YDC_API_KEY": "<your-api-key>"
9      }
10    }
11  }
12}

Zed MCP Setup | Download Zed

Codex:

Edit ~/.codex/config.toml:

1[mcp_servers.ydc-search]
2command = "npx"
3args = ["@youdotcom-oss/mcp"]
4
5[mcp_servers.ydc-search.env]
6YDC_API_KEY = "<your-api-key>"

opencode:

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

1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "ydc-search": {
5      "type": "local",
6      "command": ["npx", "@youdotcom-oss/mcp"],
7      "enabled": true,
8      "env": {
9        "YDC_API_KEY": "<your-api-key>"
10      }
11    }
12  }
13}

Qodo Gen:

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

Qodo Gen Documentation

LM Studio:

Edit mcp.json in LM Studio settings using the standard configuration template.

Download LM Studio

Gemini 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

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:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "type": "stdio",
5      "command": "bun",
6      "args": ["/full/path/to/youdotcom-mcp-server/src/stdio.ts"],
7      "env": {
8        "YDC_API_KEY": "<your-api-key>"
9      }
10    }
11  }
12}

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:

1version: '3.8'
2services:
3  you-mcp-server:
4    build: .
5    ports:
6      - "4000:4000"
7    environment:
8      - YDC_API_KEY=${YDC_API_KEY}
9      - PORT=4000
10    restart: unless-stopped

Run with:

$docker-compose up -d

Configure Claude Code with Docker:

1{
2  "mcpServers": {
3    "ydc-search": {
4      "type": "http",
5      "url": "http://localhost:4000/mcp",
6      "headers": {
7        "Authorization": "Bearer <your-api-key>"
8      }
9    }
10  }
11}

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 headers

Endpoint: https://api.you.com/mcp

Stdio Transport

Use for:

  • Local NPM package installations
  • Development environments
  • IDEs that only support stdio

Authentication: Environment variable

Command: npx @youdotcom-oss/mcp

Troubleshooting

Symptoms: Authentication errors, “Invalid API key” messages

Solutions:

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

Symptoms: “Connection refused”, timeout errors

Solutions:

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

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

Solutions:

  1. Restart your IDE after configuration changes
  2. Check the IDE’s MCP logs for error messages
  3. Verify the configuration file is in the correct location
  4. For stdio transport, ensure the command is executable
  5. 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