MCP Server

Introduction

The You.com MCP Server is the fastest path from zero to web-grounded AI agents. Give your agents real-time access to the latest web information through the Model Context Protocol. 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:

• Free to start — use you-search without credentials on the remote server (?profile=free) or the local NPM package
• Web and news search with advanced filtering
• Content extraction from URLs in markdown or HTML format
• Finance-optimized research with a dedicated financial index
• Multiple deployment options: Remote server (recommended) or local NPM package
• Optional API key for higher rate limits
• OAuth 2.1 support on the remote server — any MCP client that implements the OAuth 2.1 authorization flow connects without managing 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 three simple steps:

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

1
{
2
  "mcpServers": {
3
    "ydc-server": {
4
      "type": "http",
5
      "url": "https://api.you.com/mcp?profile=free"
6
    }
7
  }
8
}

1
{
2
  "mcpServers": {
3
    "ydc-server": {
4
      "command": "npx",
5
      "args": ["@youdotcom-oss/mcp"]
6
    }
7
  }
8
}

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

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

Authentication

Remote server (https://api.you.com/mcp) supports one of:

• Bearer token — pass Authorization: Bearer <your-api-key> as a request header. Get a key at you.com/platform.
• OAuth 2.1 — no API key needed. Any MCP client that implements MCP Authorization will automatically handle the flow. When you connect without credentials, the server responds with 401 Unauthorized and a WWW-Authenticate header pointing to the You.com authorization server. Your client opens a browser for you to sign in, then retries the connection with the issued token.
• Free tier — no credentials required. Connect to https://api.you.com/mcp?profile=free for unauthenticated access to you-search only. you-contents, you-research, and you-finance are excluded from this profile. Limited to 100 queries per day.

Local NPM package (npx @youdotcom-oss/mcp) uses STDIO transport:

• Free tier — run without any YDC_API_KEY env var. Subject to free-tier rate limits.
• API key — set YDC_API_KEY=<your-api-key> in the environment for higher rate limits.
• Tool scoping — set YDC_ALLOWED_TOOLS to a comma-separated list of tool ids to expose. For example, YDC_ALLOWED_TOOLS=you-search,you-finance makes only those two tools available.
• Free profile — set YDC_PROFILE=free for search-only mode with no authentication. This overrides YDC_ALLOWED_TOOLS and does not expose you-research, you-contents, you-finance, or livecrawl.

Available tools

The You.com MCP Server provides four tools. Three are enabled by default; you-finance is optional and must be requested explicitly. 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-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.

you-research

Comprehensive web research that returns synthesized, citation-backed answers. Use this when you need in-depth analysis of a topic rather than raw search results. Supports configurable effort levels—lite, standard, deep, and exhaustive—so you can balance speed against thoroughness.

you-finance (optional)

Finance-optimized research with a dedicated financial index covering structured company fundamentals, equity and commodity price data, private company metrics, SEC filings, and financial news. Use this when you need citation-backed answers to financial questions—earnings analysis, market research, due diligence, and macroeconomic research. you-finance is not included in the default tool set. Request it explicitly with ?tools= on the remote server or YDC_ALLOWED_TOOLS on the local package (see Scoping tools below).

Scoping tools

The default MCP endpoint (https://api.you.com/mcp) exposes three tools: you-search, you-research, and you-contents. you-finance is not included by default. You can control which tools are visible in two ways.

Using the ?tools= query parameter (recommended)

Append ?tools= with a comma-separated list of tool ids to scope the visible tool set. This is the simplest approach and works with any HTTP MCP client.

Finance only:

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

Search plus finance:

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

All four tools:

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

Using the X-Disable-Tools header

When you use HTTP transport, you can also hide tools from the MCP session by sending the X-Disable-Tools header on each request. List tool names as a comma-separated list. Omit the header or leave it empty to register all tools.

Add the header in your MCP client configuration alongside any other headers (for example Authorization):

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

This applies to Streamable HTTP connections. The local NPM package uses STDIO transport and does not use this header.

Local NPM package tool scoping

For the local NPM package (npx @youdotcom-oss/mcp), use the YDC_ALLOWED_TOOLS environment variable instead of ?tools=:

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

You can also set YDC_PROFILE=free for search-only mode with no authentication. YDC_PROFILE takes precedence over YDC_ALLOWED_TOOLS.

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”

Content extraction & analysis

Extracting web content:

• “Extract the content from this blog post: 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”

Financial research (requires you-finance)

When you-finance is enabled, your AI assistant can answer financial questions with citation-backed sources from a finance-optimized index:

• “What were the key drivers of NVIDIA’s revenue growth in fiscal year 2025?”
• “Compare the gross margins of Apple, Microsoft, and Google over the past three fiscal years”
• “What are the key risk factors disclosed in Palantir’s most recent 10-K filing?”
• “How has the Federal Reserve’s rate path affected commercial real estate valuations since 2022?”

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

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

$
claude mcp add --transport http ydc-server https://api.you.com/mcp

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

Additional resources

For complete details on search parameters, response formats, and advanced usage, see the Search API Reference.

Troubleshooting

Report an issue

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

• Email: [email protected]
• Web: You.com Support
• GitHub: Report an issue

For contributors

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

Need technical details? Check 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
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:

Resources

Framework integrations

The You.com MCP server also powers native framework integrations. These packages connect to the same hosted MCP server at https://api.you.com/mcp and expose the same tools through framework-specific APIs:

Explore further