# MCP Server

> Integrate You.com's powerful web access capabilities into your agentic IDE using the Model Context Protocol (MCP). Search, extract content, and get AI-powered answers. Quick setup for Claude Code, Cursor, VS Code, and more.

## Introduction

The You.com MCP Server gives your AI agents **real-time access to the latest web information** through the [Model Context Protocol](https://modelcontextprotocol.io/). Search current content, get up-to-date answers, and extract live web pages—whether in your IDE or deployed agentic workflows. Built on MCP to **work everywhere your agents do**—one integration, unlimited compatibility across IDEs, frameworks, and production systems.

**Key Features:**

* 🔍 Web and news search with advanced filtering
* 🤖 AI-powered answers with optional web search integration
* 📄 Content extraction from URLs in markdown or HTML format
* 🚀 Multiple deployment options: Remote server (recommended) or local NPM package
* 🔒 Secure authentication with API keys
* 🌐 Works seamlessly with Windsurf, Claude Code, Cursor, VS Code, JetBrains, and other MCP-enabled IDEs

## Getting started

Get up and running with the You.com MCP Server in four simple steps:

### Step 1: Get your API key

Visit [you.com/platform](https://you.com/platform) to obtain your API key. Keep this key secure - you'll need it for configuration.

### Step 2: Choose your setup

You can discover this server in the [Anthropic MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.youdotcom-oss%2Fmcp) as `io.github.youdotcom-oss/mcp`, or configure it manually:

<CardGroup cols={2}>
  <Card title="Remote server (recommended)" icon="fa-regular fa-cloud">
    Always up-to-date with the latest features. Just add the URL `https://api.you.com/mcp` and your API key to your agent's configuration.
  </Card>

  <Card title="Local NPM package" icon="fa-regular fa-box">
    For self-hosting or offline development. Install via `npx @youdotcom-oss/mcp` to run locally on your machine with STDIO transport.
  </Card>
</CardGroup>

### Step 3: Configure your client

Choose from Windsurf, Claude Code, Cursor, VS Code, JetBrains, or other supported editors. See the [Setup guides](#setup-guides) below for IDE-specific configuration.

#### Standard configuration templates

Most MCP clients use one of these standard configuration formats:

**Remote server (recommended):**

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

**Local NPM package:**

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

### Step 4: Test your setup

Once configured, try these natural language queries with your AI assistant:

* "Search the web for the latest news about artificial intelligence"
* "What is the capital of France?" (with web search)
* "Extract the content from [https://example.com](https://example.com)"

Your AI assistant will ask for permission to use the You.com MCP tools the first time, then automatically use them for future requests.

## Available tools

The You.com MCP Server provides three powerful tools that work seamlessly with your AI assistant. Simply ask in natural language what you want to do - your MCP client automatically handles the rest.

### you-search

Comprehensive web and news search with advanced filtering capabilities. Use this when you need to search the web for information, filter by specific sites or file types, or get the latest news on a topic.

### you-express

Fast AI-powered agent that provides synthesized answers with optional real-time web search. Use this when you want a direct answer to a question with up-to-date context and citations.

### you-contents

Extract full page content from URLs in markdown or HTML format. Use this when you need to extract and analyze content from web pages for reading or processing in your workflow.

## Use cases & examples

Here are practical examples showing how to use the You.com MCP tools in your daily workflow:

### Research & information gathering

**Finding specific information:**

* "Find recent research papers about quantum computing on arxiv.org"
* "Search for TypeScript documentation about generics"
* "Get the latest news about renewable energy from the past week"
* "Find PDF files about machine learning algorithms"

**Getting synthesized answers:**

* "What are the key differences between REST and GraphQL?"
* "Explain how quantum entanglement works"
* "What happened in the tech industry today?"
* "Summarize the main features of the latest Python release"

### Content extraction & analysis

**Extracting web content:**

* "Extract the content from this blog post: [https://example.com/article](https://example.com/article)"
* "Get the documentation from these three URLs in markdown format"
* "Pull the HTML content from this page preserving the layout"
* "Batch extract content from these 5 documentation pages"

### Combined workflows

Your AI assistant can orchestrate multiple tools to complete complex tasks:

1. **Research + extract**: "Search for the best TypeScript tutorials, then extract the content from the top 3 results"
2. **Question + deep dive**: "What is WebAssembly? Then search for real-world examples and extract code samples"
3. **News + analysis**: "Find recent articles about AI regulation, then summarize the key points"

### Pro tips

* **Be specific**: Include domains, date ranges, or file types when searching for more precise results
* **Use natural language**: You don't need to memorize parameters - just describe what you want
* **Ask follow-up questions**: Refine results and dig deeper by asking your AI assistant to clarify or expand
* **Let your agent orchestrate**: For complex workflows, your AI assistant will automatically use multiple tools together

## Setup guides

<AccordionGroup>
  <Accordion title="Windsurf" icon="wind" defaultOpen>
    For setup, follow the MCP installation [guide](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin).
  </Accordion>

  <Accordion title="Claude Code" icon="code">
    **Quick setup:**

    ```bash
    claude mcp add --transport http ydc-server https://api.you.com/mcp --header "Authorization: Bearer <your-api-key>"
    ```

    For setup, follow the MCP installation [guide](https://code.claude.com/docs/en/mcp).
  </Accordion>

  <Accordion title="Claude Desktop" icon="desktop">
    For setup, follow the MCP installation [guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
  </Accordion>

  <Accordion title="Cursor IDE" icon="arrow-pointer">
    [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ydc-server\&config=eyJ1cmwiOiJodHRwczovL2FwaS55b3UuY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8eW91LWFwaS1rZXk%2BIn19)

    For setup, follow the MCP installation [guide](https://cursor.com/docs/context/mcp#installing-mcp-servers); use the configuration template above **without** the `type` field.

    <Note>
      To avoid conflicts, go to Settings → Agents tab and turn off Cursor's built-in web search tool.
    </Note>
  </Accordion>

  <Accordion title="VS Code" icon="code">
    **Quick setup (command line):**

    ```bash
    code --add-mcp '{"name":"ydc-server","url":"https://api.you.com/mcp","type":"http","headers":{"Authorization":"Bearer <your-api-key>"}}'
    ```

    For setup, follow the MCP installation [guide](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_add-an-mcp-server); use the configuration template above.

    <Note>
      **Requirements:**

       GitHub Copilot extension must be installed
    </Note>
  </Accordion>

  <Accordion title="JetBrains IDEs" icon="code">
    For setup, follow the MCP installation [guide](https://www.jetbrains.com/help/ai-assistant/mcp.html#connect-to-an-mcp-server); use the configuration template above.

    **Supported IDEs:** IntelliJ IDEA, PyCharm, WebStorm, GoLand, RubyMine, PhpStorm, and more (requires AI Assistant enabled)
  </Accordion>

  <Accordion title="Zed Editor" icon="pen-to-square">
    For setup, follow the MCP installation [guide](https://zed.dev/docs/ai/mcp#as-custom-servers); use the configuration template above **without** the `type` field.
  </Accordion>

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

    For setup, follow the MCP installation [guide](https://github.com/openai/codex/blob/main/docs/config.md#streamable-http).

    **opencode:**

    For setup, follow the MCP installation [guide](https://opencode.ai/docs/mcp-servers/#remote); use the configuration template above.

    **LM Studio:**

    For setup, follow the MCP installation [guide](https://lmstudio.ai/docs/app/mcp); use the configuration template above but **without** the `type` field.

    **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.
  </Accordion>
</AccordionGroup>

## Additional resources

For complete details on search parameters, response formats, and advanced usage, see the [Search API Reference](/api-reference/search/v1-search).

## 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. **HTTP mode:** Confirm the server is listening on the correct port
    4. Check your MCP client logs for detailed error messages
  </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 (Claude Code: terminal output, Claude Desktop: application menu, Cursor: MCP server logs in settings, VS Code: output panel)
    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>

### Report an issue

If you're experiencing issues, we're here to help:

* **Email:** [support@you.com](mailto:support@you.com)
* **Web:** [You.com Support](https://you.com/support/contact-us)
* **GitHub:** [Report an issue](https://github.com/youdotcom-oss/dx-toolkit/issues)

<Note>
  **Pro tip:**

   When errors occur, check your MCP client logs - they include a pre-filled mailto link with error details for easy reporting.
</Note>

## For contributors

Interested in contributing to the You.com MCP Server? We'd love your help!

Need technical details? Check [AGENTS.md](https://github.com/youdotcom-oss/dx-toolkit/blob/main/packages/mcp/AGENTS.md) for complete development setup, architecture overview, code patterns, and testing guidelines.

1. Fork the repository
2. Create a feature branch following naming conventions in [CONTRIBUTING.md](https://github.com/youdotcom-oss/dx-toolkit/blob/main/CONTRIBUTING.md)
3. Follow the code style guidelines and use conventional commits
4. Write tests for your changes (maintain >80% coverage)
5. Run quality checks: `bun run check && bun test`
6. Submit a pull request with a clear description

We appreciate all contributions, whether it's:

* Bug fixes
* New features
* Documentation improvements
* Performance optimizations
* Test coverage improvements

## Transport protocols

The MCP server supports two transport protocols:

<CardGroup cols={2}>
  <Card title="HTTP transport" icon="fa-regular fa-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="fa-regular fa-terminal">
    **Use for:**

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

    **Authentication:** Environment variable

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

## Resources

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

  <Card title="GitHub repository" icon="fa-brands fa-github" href="https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/mcp">
    Source code and issues
  </Card>

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

## Explore further

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

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