MCP Server

Introduction

The You.com MCP Server gives agents live web search, page extraction, citation-backed research, and finance research through the Model Context Protocol. There is one MCP server at https://api.you.com. you-research and you-finance stay off the default tool list until you connect to /mcp/research or /mcp/finance, or you name them with ?tools= or X-Allowed-Tools on /mcp.

On /mcp, the server takes the intersection of what your profile allows (the ceiling) and what you asked for (header or query param). Auth is resolved independently of tool selection, except that the free and discover profiles are both keyless and pre-capped.

Base URL: https://api.you.com. Trailing-slash POST variants work (POST /mcp/ is accepted). Other HTTP methods return 405.

Endpoints

This server has six tools: you-search, you-contents, you-research, you-finance, you-balance, and you-discover. There is no you-answer tool on this server.

Research and finance are the two tools missing from that default list. Pick a dedicated path when the URL should force one of them, or stay on /mcp and pass an allowlist when one connection should expose a mix.

Dedicated paths

POST /mcp/research forces the allowlist to you-research. POST /mcp/finance forces it to you-finance. Both use the same handler as /mcp. A ?tools= query or X-Allowed-Tools header on these URLs is ignored. The profile ceiling still applies.

Pros

• The URL names the tool (/mcp/research or /mcp/finance).
• The client lists that one tool, so the agent is not choosing among search, contents, and research on every turn.
• /mcp/research and /mcp/finance include that tool even when ?tools= is absent.
• ?tools= and X-Allowed-Tools are ignored, so they do not replace the forced tool.

Cons

• Research and finance as separate connections means two MCP server entries.
• The dedicated path does not also expose you-search, you-contents, or you-balance.
• An incompatible profile still returns an empty tool list. POST /mcp/finance?profile=free is {you-finance} ∩ {you-search, you-discover}, so the client sees nothing.

Base endpoint plus an allowlist

POST /mcp?tools=you-search,you-research,you-finance keeps that mix on one connection. A non-empty X-Allowed-Tools header does the same job and wins over ?tools=. Omit both and the server returns the default four: you-search, you-contents, you-balance, and you-discover.

Enabled tools are still the profile ceiling intersected with the allowlist. The rules are in How Enabled Tools Are Resolved.

Pros

• One entry can include you-search, you-research, and you-finance together.
• One Authorization header covers every tool on that entry.
• The allowlist can name one tool or several.

Cons

• https://api.you.com/mcp with no ?tools= and no X-Allowed-Tools header omits research and finance.
• Each added tool is another choice the agent sees on every turn.
• The tool has to sit in the profile ceiling and the allowlist. POST /mcp?profile=free&tools=you-research returns no tools.

Multiple You.com entries

In ~/.cursor/mcp.json, leave out the type field. The block below registers five You.com servers: keyless free, keyless discover, a mixed allowlist, dedicated research, and dedicated finance.

you.com_free and you.com_discover take no API key. you.com_search, you.com_research, and you.com_finance_research include research or finance, so add Authorization: Bearer <YDC_API_KEY> on those entries, or omit the header and complete OAuth 2.1 if the client starts that flow.

{
  "mcpServers": {
    "you.com_free": {
      "url": "https://api.you.com/mcp?profile=free"
    },
    "you.com_discover": {
      "url": "https://api.you.com/mcp?profile=discover"
    },
    "you.com_search": {
      "url": "https://api.you.com/mcp?tools=you-search,you-research,you-finance",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>"
      }
    },
    "you.com_research": {
      "url": "https://api.you.com/mcp/research",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>"
      }
    },
    "you.com_finance_research": {
      "url": "https://api.you.com/mcp/finance",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>"
      }
    }
  }
}

How Enabled Tools Are Resolved

Enabled tools = profile ceiling ∩ allowed-tools, computed on every request. A tool must appear in both sets or the client does not see it. The header, query param, and default allowlist are alternatives, not a union.

1. Profile ceiling (?profile=)

The profile is a server-managed cap.

2. Allowed-tools (client-managed)

Priority is first match, not a union:

1. X-Allowed-Tools header (comma-separated) if the value is non-empty
2. else ?tools= query param
3. else the default: you-search, you-contents, you-balance, you-discover

The default excludes you-research and you-finance. Reach those async tools through /mcp/research and /mcp/finance, or by allowing them explicitly on /mcp.

3. Endpoint forcing

/mcp/finance and /mcp/research replace layer 2 entirely. The profile ceiling still applies.

POST /mcp/finance?profile=free is {you-finance} ∩ {you-search, you-discover} → zero tools, with no error.

Worked combinations

Allowed Tools

Using the ?tools= query parameter

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

Finance only (or use POST /mcp/finance):

{
  "mcpServers": {
    "ydc-server": {
      "type": "http",
      "url": "https://api.you.com/mcp?tools=you-finance",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>"
      }
    }
  }
}

Search plus finance:

{
  "mcpServers": {
    "ydc-server": {
      "type": "http",
      "url": "https://api.you.com/mcp?tools=you-search,you-finance",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>"
      }
    }
  }
}

Research base (search plus contents, no managed research):

Scoping to you-search and you-contents keeps the slower, higher-cost you-research tool out of the list so the agent runs its own search-read-synthesize loop. The you-research agent skill pins this allowlist for that reason.

{
  "mcpServers": {
    "ydc-server": {
      "type": "http",
      "url": "https://api.you.com/mcp?tools=you-search,you-contents",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>"
      }
    }
  }
}

All six tools:

{
  "mcpServers": {
    "ydc-server": {
      "type": "http",
      "url": "https://api.you.com/mcp?tools=you-search,you-contents,you-research,you-finance,you-balance,you-discover",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>"
      }
    }
  }
}

Using the X-Allowed-Tools header

On HTTP transport, send X-Allowed-Tools as a comma-separated allowlist. A non-empty header wins over ?tools= and over the default. Omit the header (or send it empty) to fall through to ?tools= or the default four-tool list.

{
  "mcpServers": {
    "ydc-server": {
      "type": "http",
      "url": "https://api.you.com/mcp",
      "headers": {
        "Authorization": "Bearer <YDC_API_KEY>",
        "X-Allowed-Tools": "you-search,you-finance"
      }
    }
  }
}

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 npx @youdotcom-oss/mcp, set YDC_ALLOWED_TOOLS instead of ?tools= or X-Allowed-Tools, and YDC_PROFILE instead of ?profile=. Enabled tools are still the intersection of those two values.

{
  "mcpServers": {
    "ydc-server": {
      "command": "npx",
      "args": ["@youdotcom-oss/mcp"],
      "env": {
        "YDC_API_KEY": "<YDC_API_KEY>",
        "YDC_ALLOWED_TOOLS": "you-search,you-finance"
      }
    }
  }
}

YDC_PROFILE=free caps the local package to you-search and you-discover with no authentication. When YDC_ALLOWED_TOOLS is set, enabled tools are the intersection of that ceiling and the allowlist. A run with neither YDC_API_KEY nor YDC_PROFILE=free has no credentials and requests fail.

Available Tools

The server provides these six tools. Bare POST /mcp shows the default four (you-search, you-contents, you-balance, you-discover). Ask in natural language what you want to do. Your MCP client handles the tool call.

you-search

Web and news search with filtering. Use this when you need current web results, site or file-type filters, or recent news. See Search Parameter Control for model-facing parameters and host-supplied overrides.

you-contents

Extract full page content from URLs in markdown or HTML. Use this when you already have URLs and need the page for reading or processing.

you-research

Multi-step web research that returns a synthesized, citation-backed answer. Use this when you need in-depth analysis rather than raw search results. Supports configurable effort levels: lite, standard, deep, exhaustive, and frontier. Not in the default allowlist. Call POST /mcp/research, or allow you-research on /mcp.

you-finance

Finance-optimized research over a dedicated financial index: company fundamentals, equity and commodity prices, private company metrics, SEC filings, and financial news. Use this for earnings analysis, market research, due diligence, and macroeconomic questions. Not in the default allowlist. Call POST /mcp/finance, or allow you-finance on /mcp.

you-discover

Find the right You.com integration path for an agentic project: API, MCP server, SDK, docs page, plugin, or framework. Use this when you are wiring You.com into a new agent and want pointed recommendations.

you-balance

Return the remaining credit balance for the API key in use. The balance comes back in cents. Divide by 100 for USD. Always requires a user API key. Payment headers do not unlock it.

Search Parameter Control

you-search accepts parameters at two levels: the common search parameters the model sets naturally, and a deeper integration lane that gives your host application full parameter control.

Model-facing parameters (common)

These are part of the tool’s input schema, so your agent sets them conversationally—no special handling needed:

• query, count, freshness, offset—the core search shape
• extraction, extraction_source, crawl_timeout—page-content retrieval tuning
• knowledge, safesearch—result enrichment and moderation
• exclude_domains—domain exclusion

Inline search operators in the query (site:, lang:, loc:, filetype:) map to the same underlying parameters automatically.

Host-supplied overrides (deep integration)

For full parameter control, your host application can supply overrides out-of-band on each tools/call under the reserved _meta key com.you.com/search (or equivalently as X-Search-* HTTP headers). These overrides don’t have to be model-generated, and they always win over model-supplied arguments:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "you-search",
    "arguments": { "query": "EV tax incentives" },
    "_meta": {
      "com.you.com/search": {
        "country": "US",
        "language": "EN",
        "count": 20,
        "include_domains": ["irs.gov", "energy.gov"],
        "safesearch": "strict"
      }
    }
  }
}

Every override field is optional. The supported set:

• Hybrid—also settable by the model: count, extraction, extraction_source, knowledge, exclude_domains, safesearch, crawl_timeout
• Host-only—settable here only, never exposed to the model: language, country, include_domains, boost_domains

{
  "name": "you-search",
  "_meta": {
    "com.you.com/search": {
      "description": "Host-supplied search overrides. Send an object under the com.you.com/search key in tools/call params._meta (or X-Search-* HTTP headers); every field is optional and wins over model-supplied arguments. Host-only fields (language, country, include_domains, boost_domains) are settable here and never by the model.",
      "schema": {
        "type": "object",
        "properties": {
          "count": { "type": "integer", "minimum": 1, "maximum": 100 },
          "country": { "type": "string", "enum": ["AR", "AU", "AT", "...", "US"] },
          "safesearch": { "type": "string", "enum": ["off", "moderate", "strict"] }
        }
      }
    }
  }
}

Merge and validation behavior

• Precedence—field-level merge: X-Search-* headers beat _meta, which beats model-supplied arguments
• Unknown keys and headers are ignored—an invalid value on a recognized field surfaces a named tool error rather than a silent fallback
• Domain guards—include_domains cannot be combined with exclude_domains or boost_domains. Domain lists are capped at 500 (error, not truncation)
• Inline operators—site:, lang:, and loc: operators stay raw in the query when the corresponding explicit override is present

Authentication

Auth does not choose the tool list. A tool can be visible and still fail at call time if the request is missing credentials.

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

• Keyless profiles—free and discover skip auth. free exposes you-search and you-discover (100 queries per day). discover exposes you-discover.
• Payment authorization—x402 headers (PAYMENT-SIGNATURE or X-PAYMENT) and Machine Payments Protocol (Authorization: Payment) bypass local auth for keyless-capable tools: you-search, you-contents, you-research, you-finance, and you-discover. The server forwards those headers to the upstream API. you-balance still requires an API key. See Machine Payments for protocol details.
• Bearer token—Authorization: Bearer <YDC_API_KEY>. Get a key at you.com/platform.
• OAuth 2.1—when OAuth is enabled, an MCP client that implements MCP Authorization can connect without a key. The server responds with 401 Unauthorized and a WWW-Authenticate header pointing at the You.com authorization server. The client opens a browser for sign-in, then retries with the issued token.

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

• Set YDC_PROFILE=free for keyless access. The free ceiling is you-search and you-discover (100 queries per day). A run with neither YDC_API_KEY nor YDC_PROFILE=free has no credentials and requests fail.
• Set YDC_API_KEY=<YDC_API_KEY> for keyed access.
• Set YDC_ALLOWED_TOOLS for the allowlist. Enabled tools are still the intersection of the profile ceiling and that allowlist (see Allowed Tools).

Gotchas

1. Bare /mcp with no header and no ?tools= shows four tools. you-research and you-finance are absent until you allow them or use /mcp/research and /mcp/finance.
2. Unknown tool names in an allowlist are dropped, not rejected.
3. An empty intersection is a server with zero tools, not an error. That includes /mcp/finance?profile=free and any other forced-endpoint plus incompatible profile.
4. Header and query do not merge. A non-empty X-Allowed-Tools header wins outright.

Getting Started

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

Docs MCP Server

Use Cases and Examples

Research and 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 and 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?”

Setup Guides

claude mcp add --transport http ydc-server https://api.you.com/mcp --header "Authorization: Bearer <YDC_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 <YDC_API_KEY>"}}'

droid mcp add you https://api.you.com/mcp --type http

droid mcp add you https://api.you.com/mcp --type http \
  --header 'Authorization: Bearer ${YDC_API_KEY}' --no-oauth

droid mcp add you https://api.you.com/mcp --type http \
  --header 'Authorization: Bearer <YDC_API_KEY>' --no-oauth

droid mcp add you https://api.you.com/mcp?profile=free --type http --no-oauth

Additional Resources

For complete details on search parameters, response formats, and advanced usage, see the Web 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

Transport Protocols

The MCP server supports two transport protocols:

Resources

Explore Further