> For clean Markdown of any page, append `.md` to the page URL. > Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL). > Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key). > Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing. > OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`. # MCP Server ## Introduction The You.com MCP Server gives your LLMs and agents access to live web search, page extraction, citation-backed research, and finance research through the [Model Context Protocol](https://modelcontextprotocol.io/). The server is hosted at `api.you.com`, with additional paths for other tools. Connect to that host over HTTP, or run `npx @youdotcom-oss/mcp` over STDIO. Tool selection rules are in [Scope Tools](#scope-tools). > **Note** > > A separate MCP server that allows agents to search over these docs is available: [Docs MCP Server guide](/docs/agents/docs-mcp-server). ## Getting Started ### 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: #### Remote server (recommended) Hosted at `https://api.you.com/mcp`. Add that URL to your agent's configuration. #### Local NPM package For self-hosting or offline development. Install via `npx @youdotcom-oss/mcp` to run locally with STDIO transport. ### 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 #### Remote server Remote server requires an API key or OAuth 2.1. If the client supports OAuth 2.1, connect without credentials and the authorization flow starts. Otherwise, pass an API key. This URL is bare `/mcp`: ```json { "mcpServers": { "ydc-server": { "type": "http", "url": "https://api.you.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` #### Free profile Append `?profile=free`. No API key. Only Web Search is available, with rate limits. ```json { "mcpServers": { "ydc-server": { "type": "http", "url": "https://api.you.com/mcp?profile=free" } } } ``` #### Local NPM package You must set `YDC_PROFILE=free` with no key, or set `YDC_API_KEY`. ```json { "mcpServers": { "ydc-server": { "command": "npx", "args": ["@youdotcom-oss/mcp"], "env": { "YDC_PROFILE": "free" } } } } ``` With an API key and specific tools: ```json { "mcpServers": { "ydc-server": { "command": "npx", "args": ["@youdotcom-oss/mcp"], "env": { "YDC_API_KEY": "", "YDC_ALLOWED_TOOLS": "you-search,you-finance" } } } } ``` > **Note** > > Get an API key at [you.com/platform](https://you.com/platform). ### Test your setup The base remote template exposes four capabilities: general web search, web page content extraction, account balance, and tool discovery. Try: * "Search the web for this week's grid-scale battery news, then extract and summarize the top three pages" * "Extract the content from [https://example.com](https://example.com)" * "Use you-discover to pick a You.com API for a TypeScript agent" * "Find this week's articles on AI regulation and summarize the filings they cite." The client may ask for permission the first time it calls a tool. ## Authentication * **Free**—Some tools are free to use, with rate limits. Read more: [Scope Tools](#scope-tools). * **Payment authorization**—x402 headers (`PAYMENT-SIGNATURE` or `X-PAYMENT`) and Machine Payments Protocol (`Authorization: Payment`) bypass local auth for `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](/docs/administration/machine-payments). * **Bearer token**— Pass this header in your MCP client's configuration file: `Authorization: Bearer `. Get a key at [you.com/platform](https://you.com/platform). * **OAuth 2.1**—an MCP client that implements [MCP Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) can connect without a pasted key. **Local NPM package** (`npx @youdotcom-oss/mcp`) uses `YDC_API_KEY` or `YDC_PROFILE`. > **Note** > > OAuth is only available on the HTTP server. The local NPM package does not support OAuth. ## Endpoints | Endpoint | What it does | | -------------------------- | ----------------------------------------------------------------- | | `api.you.com/mcp` | General endpoint. All tools are available based on configuration. | | `api.you.com/mcp/finance` | Exclusively for `you-finance`. No tool scoping. No free usage. | | `api.you.com/mcp/research` | Exclusively for `you-research`. No tool scoping. No free usage. | The server exposes six tools: `you-search`, `you-contents`, `you-research`, `you-finance`, `you-balance`, and `you-discover`. There is no `you-answer` tool. ### Create Multiple MCP Server Entries In your MCP client's configuration file, you can create several entries, each with their own authentication and tool scoping configuration. This is useful when you want maximum control over the tools that are available to an agent, and how the agent uses them. For example, you may hook into an agent's tool call event specifically for `you-research`, and then instruct it to double-check the `research_effort` it wants to use. A simpler benefit is better cost management: dedicated API keys for high impact tools like `you-research` and `you-finance`. ```json { "mcpServers": { "you.com_free": { "url": "https://api.you.com/mcp?profile=free" }, "you.com_search_basic": { "url": "https://api.you.com/mcp?tools=you-search,you-contents", "headers": { "Authorization": "Bearer " } }, "you.com_research": { "url": "https://api.you.com/mcp/research", "headers": { "Authorization": "Bearer " } }, "you.com_finance_research": { "url": "https://api.you.com/mcp/finance", "headers": { "Authorization": "Bearer " } } } } ``` ## Scope Tools A tool is listed only when the profile ceiling and the allowlist both include it. The server computes that intersection on every request. For the allowlist, the first non-empty value wins: the `X-Allowed-Tools` header, then `?tools=`, then the default. **`profile`** `string` — default: all six tools HTTP query parameter `?profile=`. `free` allows `you-search` and `you-discover`, with no API key and 100 queries per day. `discover` allows `you-discover`, with no API key. An omitted or unknown value allows all six tools. The local package reads `YDC_PROFILE` with the same values. --- **`tools`** `string` — default: you-search,you-contents,you-balance,you-discover HTTP query parameter `?tools=`, a comma-separated allowlist. The default omits `you-research` and `you-finance`. A non-empty `X-Allowed-Tools` header replaces this value. --- **`X-Allowed-Tools`** `string` HTTP header, comma-separated. A non-empty value replaces `?tools=` and the default. An empty or omitted header leaves the query parameter or the default in place. The local package does not read this header. --- **`YDC_ALLOWED_TOOLS`** `string` Allowlist for `npx @youdotcom-oss/mcp`. Same role as `X-Allowed-Tools` on HTTP. --- `/mcp/finance` and `/mcp/research` replace the allowlist with that one tool. `?tools=` and `X-Allowed-Tools` on those paths are ignored. The profile ceiling still applies. > **Warning** > > `POST /mcp/finance?profile=free` asks for `you-finance` under the `free` ceiling, which only includes `you-search` and `you-discover`. The client sees no tools, and the server returns no error. `free` or `discover` on `/mcp/research` does the same. The same allowlist, `you-search,you-finance`, on each transport: #### Query parameter ```json { "mcpServers": { "ydc-server": { "type": "http", "url": "https://api.you.com/mcp?tools=you-search,you-finance", "headers": { "Authorization": "Bearer " } } } } ``` #### Header ```json { "mcpServers": { "ydc-server": { "type": "http", "url": "https://api.you.com/mcp", "headers": { "Authorization": "Bearer ", "X-Allowed-Tools": "you-search,you-finance" } } } } ``` #### Local package ```json { "mcpServers": { "ydc-server": { "command": "npx", "args": ["@youdotcom-oss/mcp"], "env": { "YDC_API_KEY": "", "YDC_ALLOWED_TOOLS": "you-search,you-finance" } } } } ``` > **Tip** > > `you-search,you-contents` leaves `you-research` off the list, so the agent runs its own search-read-synthesize loop. The [`you-research` agent skill](/docs/agents/skills) pins that allowlist. ## 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: ```json { "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` #### Self-describing contract via tools/list The override contract is broadcast on the tool entry itself. A `tools/list` response returns the accepted fields and their constraints in `tool._meta["com.you.com/search"]`: ```json { "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"] } } } } } } ``` Because `tools/list` results are cacheable, you can fetch the contract once and reuse it to validate overrides at runtime. #### X-Search-\* header equivalents Every override field has an HTTP header equivalent, sent alongside your other request headers: | `_meta` field | Header | | ------------------- | -------------------------------------------- | | `count` | `X-Search-Count` | | `extraction` | `X-Search-Extraction` | | `extraction_source` | `X-Search-Extraction-Source` | | `knowledge` | `X-Search-Knowledge` | | `exclude_domains` | `X-Search-Exclude-Domains` (comma-separated) | | `safesearch` | `X-Search-Safesearch` | | `crawl_timeout` | `X-Search-Crawl-Timeout` | | `language` | `X-Search-Language` | | `country` | `X-Search-Country` | | `include_domains` | `X-Search-Include-Domains` (comma-separated) | | `boost_domains` | `X-Search-Boost-Domains` (comma-separated) | ### 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 ## Setup Guides #### Windsurf For setup, follow the MCP installation [guide](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin). #### Claude Code **Quick setup (API key):** ```bash claude mcp add --transport http ydc-server https://api.you.com/mcp --header "Authorization: Bearer " ``` **OAuth 2.1 (no API key):** Connect without credentials and Claude Code will initiate the OAuth flow automatically: ```bash claude mcp add --transport http ydc-server https://api.you.com/mcp ``` For setup, follow the MCP installation [guide](https://code.claude.com/docs/en/mcp). #### Claude Desktop Local config lives in `claude_desktop_config.json`: * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Paste the local NPM package template from [Getting Started](#getting-started), then restart Claude Desktop. For setup, follow the MCP installation [guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers). #### Cursor IDE [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ydc-server\&config=eyJ1cmwiOiJodHRwczovL2FwaS55b3UuY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8eW91LWFwaS1rZXk%2BIn19) Config file: `~/.cursor/mcp.json`. For setup, follow the MCP installation [guide](https://cursor.com/docs/context/mcp#installing-mcp-servers). Omit the `type` field. To run free, discover, a mixed allowlist, research, and finance as separate entries, paste the [multiple You.com entries](#multiple-youcom-entries) block. Keyed entries need `Authorization: Bearer ` or OAuth. `?profile=free` and `?profile=discover` stay keyless. > **Note** > > To avoid conflicts, go to Settings → Agents tab and turn off Cursor's built-in > web search tool. #### VS Code **Quick setup (command line):** ```bash code --add-mcp '{"name":"ydc-server","url":"https://api.you.com/mcp","type":"http","headers":{"Authorization":"Bearer "}}' ``` 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 #### JetBrains IDEs 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) #### Zed Editor 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. #### Factory Droid **Quick setup (OAuth, no API key):** ```bash droid mcp add you https://api.you.com/mcp --type http ``` Droid initiates the OAuth 2.1 flow automatically. Run `/mcp` inside a Droid session to complete the browser sign-in. **API key with env injection (recommended for secrets):** ```bash droid mcp add you https://api.you.com/mcp --type http \ --header 'Authorization: Bearer ${YDC_API_KEY}' --no-oauth ``` Droid expands `${YDC_API_KEY}` at connection time, so the key stays out of the config file. Add `--no-oauth` to prevent Droid from attempting OAuth alongside the header. **Hardcoded API key:** ```bash droid mcp add you https://api.you.com/mcp --type http \ --header 'Authorization: Bearer ' --no-oauth ``` **Free profile (no account):** ```bash droid mcp add you https://api.you.com/mcp?profile=free --type http --no-oauth ``` **Verify:** `droid mcp list` or `/mcp` inside a Droid session. For setup, follow the [Factory MCP guide](https://docs.factory.ai/harness/mcp). #### Other editors **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 remote server template in [Getting Started](#getting-started). **LM Studio:** For setup, follow the MCP installation [guide](https://lmstudio.ai/docs/app/mcp). Use the remote server template in [Getting Started](#getting-started), 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. ## Troubleshooting #### API key issues **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 the local NPM package, verify the `YDC_API_KEY` environment variable is properly exported 5. On the remote server, try OAuth 2.1, described in [Authentication](#authentication) #### OAuth issues **Symptoms:** Browser window doesn't open, OAuth flow fails, "Invalid token" errors **Solutions:** 1. Confirm your MCP client supports OAuth 2.1—check your client's documentation 2. If the browser window opens but authorization fails, try signing in to [you.com](https://you.com) first in the same browser 3. If the flow completes but the client still receives 401, restart the MCP client to clear cached token state 4. As a fallback, use an API key from [you.com/platform](https://you.com/platform) instead #### Connection issues **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. Confirm the URL is `https://api.you.com/mcp`, `/mcp/research`, or `/mcp/finance` 4. Check your MCP client logs for detailed error messages #### IDE integration issues **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 #### Zero tools listed **Symptoms:** The server connects but `tools/list` is empty **Cause:** The profile ceiling ∩ allowed-tools intersection is empty. Common cases: `POST /mcp/finance?profile=free`, `POST /mcp/research?profile=discover`, or an allowlist that names only tools the profile forbids. **Solutions:** 1. Drop `?profile=` (or use a profile whose ceiling includes the tool) 2. On `/mcp/finance` and `/mcp/research`, the path already forces the allowlist. A `free` or `discover` profile on that URL empties the list 3. Check `X-Allowed-Tools` and `?tools=` for a non-empty header that replaced the query string ### Report an Issue * **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/mcp/issues) > **Note** > > MCP client logs include a pre-filled mailto link with the error details. ## Resources #### [NPM package](https://www.npmjs.com/package/@youdotcom-oss/mcp) Official package on npm #### [GitHub repository](https://github.com/youdotcom-oss/mcp) Source code and issues #### [MCP specification](https://modelcontextprotocol.io/) Model Context Protocol docs