> ## Documentation Index
> Fetch the complete documentation index at: https://old-docs.you.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

## Introduction

The You.com MCP Server brings comprehensive web search capabilities to your agentic IDE through the [Model Context Protocol](https://modelcontextprotocol.io/). 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:

<CardGroup cols={2}>
  <Card title="Remote Server" icon="cloud" color="#596CED">
    **Recommended** - No installation required. Use the hosted server at `https://api.you.com/mcp` with your API key.
  </Card>

  <Card title="Local NPM Package" icon="box" color="#5061D5">
    Install via `npx @youdotcom-oss/mcp` to run locally on your machine with stdio transport.
  </Card>
</CardGroup>

### Prerequisites

1. **Get a You.com API Key**: Visit [you.com/platform](https://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):**

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

**Local NPM Package:**

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

<Note>Replace `<your-api-key>` with your actual You.com API key from [you.com/platform](https://you.com/platform)</Note>

## Setup Guides

<AccordionGroup>
  <Accordion title="Windsurf" icon="wind">
    **Setup:**

    Use the standard configuration template in your Windsurf settings:

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

    [Windsurf MCP Documentation](https://docs.windsurf.com/windsurf/cascade/mcp) | [Download Windsurf](https://docs.windsurf.com/windsurf/getting-started)
  </Accordion>

  <Accordion title="Claude Code" icon="code" defaultOpen>
    **Quick Setup (CLI):**

    ```bash theme={null}
    # 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:

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

    **Manual Setup - Local NPM Package:**

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

    <Note>Replace `<your-api-key>` with your actual You.com API key from [you.com/platform](https://you.com/platform)</Note>
  </Accordion>

  <Accordion title="Claude Desktop" icon="desktop">
    **Configuration:**

    Add to your Claude Desktop MCP configuration file:

    **Remote Server:**

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

    **Local Package:**

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

    [Download Claude Desktop](https://claude.ai/download) | [MCP Setup Guide](https://docs.anthropic.com/en/docs/build-with-claude/computer-use)
  </Accordion>

  <Accordion title="Cursor IDE" icon="arrow-pointer">
    **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:

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

    <Warning>For Cursor, remove the `"type"` field from the configuration.</Warning>

    [Cursor Documentation](https://docs.cursor.com/en/context/mcp) | [Download Cursor](https://cursor.com)
  </Accordion>

  <Accordion title="VS Code" icon="code">
    **Quick Setup (Command Line):**

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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:

    ```json theme={null}
    {
      "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}"
          }
        }
      }
    }
    ```

    <Note>**Requirements:** GitHub Copilot extension must be installed</Note>

    [VS Code MCP Documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_commandline-configuration) | [Download VS Code](https://code.visualstudio.com/)
  </Accordion>

  <Accordion title="JetBrains IDEs" icon="code">
    **Configuration:**

    Since JetBrains IDEs only support stdio transport, use [mcp-remote](https://www.npmjs.com/package/mcp-remote) to bridge HTTP to stdio:

    ```json theme={null}
    {
      "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:**

    ```json theme={null}
    {
      "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](https://www.jetbrains.com/help/ai-assistant/mcp.html)
  </Accordion>

  <Accordion title="Zed Editor" icon="pen-to-square">
    **Setup:**

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

    **Remote Server (using mcp-remote):**

    ```json theme={null}
    {
      "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:**

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

    [Zed MCP Setup](https://zed.dev/docs/ai/mcp) | [Download Zed](https://zed.dev)
  </Accordion>

  <Accordion title="Other Editors" icon="ellipsis">
    **Codex:**

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

    ```toml theme={null}
    [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`:

    ```json theme={null}
    {
      "$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:**

    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](https://docs.qodo.ai/qodo-documentation/qodo-gen)

    **LM Studio:**

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

    [Download LM Studio](https://lmstudio.ai/)

    **Gemini CLI:**

    Follow the [MCP server setup guide](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) using the standard configuration template.

    **Goose:**

    Go to "Advanced settings" → "Extensions" → "Add custom extension" and use the standard configuration template.

    [Goose Installation Guide](https://block.github.io/goose/docs/getting-started/installation)
  </Accordion>
</AccordionGroup>

## Search Tool Reference

<Note>
  **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"`.
</Note>

### 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](/api-reference/search).

**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

<AccordionGroup>
  <Accordion title="Local Development Setup" icon="laptop-code">
    For developers who want to contribute or customize the MCP server:

    <Note>
      **External Contributors:** If you're outside of You.com and want to contribute, visit the [open-source repository](https://github.com/youdotcom-oss/youdotcom-mcp-server) to open pull requests or file issues.
    </Note>

    **Prerequisites:**

    * Bun 1.2.21 or higher
    * You.com API key

    **Clone and Setup:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    # 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:**

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

  <Accordion title="Docker Deployment" icon="docker">
    Deploy the MCP server using Docker for production environments:

    **Build and Run:**

    ```bash theme={null}
    # 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`:

    ```yaml theme={null}
    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:

    ```bash theme={null}
    docker-compose up -d
    ```

    **Configure Claude Code with Docker:**

    ```json theme={null}
    {
      "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.
  </Accordion>
</AccordionGroup>

## Transport Protocols

The MCP server supports two transport protocols:

<CardGroup cols={2}>
  <Card title="HTTP Transport" icon="globe">
    **Use for:**

    * Remote server connections
    * Web applications
    * Production deployments

    **Authentication:** Bearer token in headers

    **Endpoint:** `https://api.you.com/mcp`
  </Card>

  <Card title="Stdio Transport" icon="terminal">
    **Use for:**

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

    **Authentication:** Environment variable

    **Command:** `npx @youdotcom-oss/mcp`
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API Key Issues" icon="key">
    **Symptoms:** Authentication errors, "Invalid API key" messages

    **Solutions:**

    1. Verify your API key is active at [you.com/platform](https://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
  </Accordion>

  <Accordion title="Connection Issues" icon="network-wired">
    **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
  </Accordion>

  <Accordion title="IDE Integration Issues" icon="code">
    **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
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={3}>
  <Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@youdotcom-oss/mcp">
    Official package on npm
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/youdotcom-oss/youdotcom-mcp-server">
    Source code and issues
  </Card>

  <Card title="MCP Specification" icon="book" href="https://modelcontextprotocol.io/">
    Model Context Protocol docs
  </Card>
</CardGroup>

## Explore Further

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="play" href="/get-started/quickstart" horizontal>
    Get started with You.com API
  </Card>

  <Card title="Search API Reference" icon="magnifying-glass" href="/api-reference/search" horizontal>
    Detailed API documentation
  </Card>
</CardGroup>