Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@You.com MCP Server Search the web for the latest AI news"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Bin-only STDIO bridge for the hosted You.com MCP server at https://api.you.com/mcp.
This package does not register tools locally and does not contain REST tool logic. Its only job is to proxy STDIO MCP traffic to the hosted remote server.
// Add this to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.)
// Free tier — no API key, no signup.
{
"mcpServers": {
"you": {
"command": "npx",
"args": ["@youdotcom-oss/mcp"],
"env": { "YDC_PROFILE": "free" }
}
}
}If your client supports remote MCP, point it at https://api.you.com/mcp?profile=free directly — no local process needed.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"you": {
"command": "npx",
"args": ["@youdotcom-oss/mcp"],
"env": { "YDC_PROFILE": "free" }
}
}
}Authenticated (all default tools):
{
"mcpServers": {
"you": {
"command": "npx",
"args": ["@youdotcom-oss/mcp"],
"env": { "YDC_API_KEY": "<your-key>" }
}
}
}# Free tier
claude mcp add you -e YDC_PROFILE=free -- npx @youdotcom-oss/mcp
# Authenticated
claude mcp add you -e YDC_API_KEY=<your-key> -- npx @youdotcom-oss/mcpAdd to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"you": {
"command": "npx",
"args": ["@youdotcom-oss/mcp"],
"env": { "YDC_PROFILE": "free" }
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"you": {
"command": "npx",
"args": ["@youdotcom-oss/mcp"],
"env": { "YDC_PROFILE": "free" }
}
}
}Add to your user or workspace mcp.json:
{
"servers": {
"you": {
"command": "npx",
"args": ["@youdotcom-oss/mcp"],
"env": { "YDC_PROFILE": "free" }
}
}
}If your client speaks streamable HTTP, skip the local bridge:
https://api.you.com/mcp?profile=freeAuthenticated:
https://api.you.com/mcp
Authorization: Bearer <your-key>Related MCP server: You.com MCP Server
bun add @youdotcom-oss/mcpOr run it directly:
npx @youdotcom-oss/mcpYDC_API_KEY
Optional. Sent as Authorization: Bearer <key>.
YDC_PROFILE
Optional. When set to free, routes the bridge to https://api.you.com/mcp?profile=free.
YDC_ALLOWED_TOOLS
Optional. Comma-separated hosted tool ids to expose through https://api.you.com/mcp?tools=....
YDC_PROFILE takes precedence over YDC_ALLOWED_TOOLS.
The default hosted MCP URL exposes four tools:
you-search
you-contents
you-balance
you-discover
Two additional tools are available on request:
you-finance
you-research
Request additional tools explicitly with tools. tools scopes the visible tool set.
Today, profile=free is a keyless mode. It overrides tools and exposes you-search and you-discover.
Examples:
Default tool set: https://api.you.com/mcp
Finance only: https://api.you.com/mcp?tools=you-finance
Search plus finance: https://api.you.com/mcp?tools=you-search,you-finance
Research only: https://api.you.com/mcp?tools=you-research
Free profile (keyless): https://api.you.com/mcp?profile=free
API keys: you.com/platform/api-keys
Platform docs: documentation.you.com
MCP registry listing: io.github.youdotcom-oss/mcp
Support: support@you.com
Development setup and code conventions live in AGENTS.md; contribution flow and PR conventions live in CONTRIBUTING.md. Issues and PRs welcome.
MIT — see LICENSE.
Discover AI agents, MCP servers, A2A agents, and skills via ARD Agent Finder services and the You.com catalog. Search-only — never installs or connects. Returns ranked results with relevance scores.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max consolidated results (1–25). | |
| query | Yes | Natural-language task to find agents/tools for. | |
| finder | No | Which external Agent Finder service(s) to query: github (GitHub Agent Finder), huggingface (Hugging Face finder), or all. The You.com catalog is always included. | all |
| Name | Required | Description |
|---|---|---|
| query | Yes | The original discovery query |
| finders | Yes | Per-finder request status |
| results | Yes | Ranked consolidated results, highest score first |
| referrals | Yes | Informational referrals to non-result resources |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful scope detail (external ARD finders plus the You.com catalog) and explicitly reassures no installation/connection occurs, but says little about ranking behavior or latency beyond 'ranked results with relevance scores'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the discover action and its resources, followed by scope and output expectations. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema and 100% schema coverage, the description only needs to frame the discovery scope and the non-installing nature, which it does. The one gap is not clarifying its relationship to you-search.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so query, limit and finder are fully documented upstream. The description adds no parameter-level meaning (e.g., how query phrasing affects results), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Discover') and concrete resources (AI agents, MCP servers, A2A agents, skills), which clearly distinguishes it from a generic search. It does not, however, reference the sibling you-search, so an agent must infer the boundary from the resource types alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Search-only — never installs or connects' clause conveys a usage boundary (discovery, not installation), but there is no explicit guidance on when to pick this over you-search or what query types suit it. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the web for current information, facts, news, and sources.
Best for: current events, facts about people, companies, and organizations, finding primary sources, verifying claims. Returns: ranked results with URLs and snippets — read them with you-contents before answering; snippets are not page content.
Query tips:
One intent per search, phrased naturally: "tariff exemptions for semiconductor imports 2026" — not a question, not a pile of synonyms.
Inline filters are mapped automatically: site:cdc.gov, lang:fr, loc:DE.
On zero results, don't repeat the query: drop exact-phrase ("quoted") constraints first, then widen — keep domain filters unless the domain itself was wrong. Or read the best prior result with you-contents.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Max results per section | |
| query | Yes | Short natural-language phrase describing one thing to find, e.g. "tariff exemptions for semiconductor imports 2026". Inline `site:`, `lang:`, `loc:` filters are mapped automatically. Max 50 words / 400 characters after operator mapping. | |
| offset | No | Pagination offset, in multiples of count. count=5 and offset=1 returns results 5–10. Range 0–9. Omit on the first page. | |
| freshness | No | Limit results to a recent window. Use it when recency matters — news, prices, releases, "this year" — and omit it for evergreen facts. Pass a named bucket (`day`, `week`, `month`, `year`) or a date range `YYYY-MM-DDtoYYYY-MM-DD`. If the query already names a timeframe, the broader of the two wins, so this can only widen, never narrow, the query phrase. | |
| knowledge | No | Licensed knowledge results are included by default (core, the only mode); matching results appear in results.knowledge. | core |
| extraction | No | Extraction mode. "highlights" (default) returns query-relevant passages; "none" returns plain snippets; "full_page" crawls each result and returns full page content. | highlights |
| safesearch | No | Content-moderation filter. Omit to let the API default (moderate) apply. | |
| crawl_timeout | No | Max seconds to wait for page content when extraction is full_page (1–60). Omit for the default 10. | |
| exclude_domains | No | Domains to exclude from search results (up to 500). Cannot be combined with inline `site:` filters, which map to include_domains. | |
| extraction_source | No | Where full-page content comes from when extraction is 'full_page'. 'cache' is included in base cost, 'fetch' bills at livecrawl rates, 'blend' bills only for pages not in cache. |
| Name | Required | Description |
|---|---|---|
| results | Yes | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, and non-destructive, so safety is covered; the description goes further by warning that returned snippets are not page content and must be followed up with you-contents, and by describing what happens on zero results. Cost and caching behavior of extraction_source is left to the schema rather than the prose, so it stops short of 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the verb and scope, then separates Returns, query tips, and failure handling with clear delimiters. Every line carries actionable content — the query example, the operator note, and the zero-results ladder — with no restatement of the name or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present it correctly avoids explaining return shapes, and with 10 params at full coverage the untouched optional knobs (safesearch, crawl_timeout, knowledge) are safe to omit. What is missing is any routing rule against you-discover, which matters given only one sibling exists and it plausibly overlaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds genuine value by giving query-craft rules (one intent per search, natural phrasing, no synonym piles) and by noting that inline site:/lang:/loc: filters are mapped automatically, which prevents the agent from duplicating them in exclude_domains or include_domains. The freshness widening rule is restated from the schema rather than extended.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Search the web") and enumerates the content classes it targets: current information, facts, news, and sources. It is clear what the tool does, but it never names or contrasts with the sibling you-discover, so an agent must infer the split between the two search entry points.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The "Best for:" block gives explicit positive selection criteria (current events, facts about people/companies, verifying claims), and the zero-results paragraph gives concrete recovery guidance rather than leaving the agent to retry blindly. Missing is the negative case: nothing says when to prefer you-discover instead, which is the one sibling that competes for the same intent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v4.0.7you-discover5 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / finder / descriptionPrevious value: -"Which Agent Finder discovery service(s) to query."New value: +"Which external Agent Finder service(s) to query: github (GitHub Agent Finder), huggingface (Hugging Face finder), or all. The You.com catalog is always included."Input schema / properties / finder_urlRemoved value: -{
- "description": "Optional custom finder URL (must be public http/https). Augments selected finders.",
- "format": "uri",
- "type": "string"
-}Input schema / properties / query / maxLengthAdded value: +2000Output schema / properties / results / items / properties / sources / descriptionPrevious value: -"Finder base URLs that returned this result"New value: +"Finder base URLs or local source identifiers that returned this result"v4.0.6you-search2 fields changedInput schema / properties / knowledge / defaultAdded value: +"core"Input schema / properties / knowledge / descriptionPrevious value: -"Include licensed knowledge results relevant to the query. core requests factual answers alongside web and news results; matching results appear in results.knowledge."New value: +"Licensed knowledge results are included by default (core, the only mode); matching results appear in results.knowledge."v4.0.5you-discoveryou-searchScored across 2 tools
you-discover targets agents/MCP servers/skills in a catalog, while you-search targets the open web — the descriptions make this boundary explicit. The only mild overlap is that both are 'search' operations returning ranked results, which could tempt misselection when an agent wants general discovery.
Both tools use the same 'you-' prefix plus a lowercase action word in kebab-case (you-discover, you-search). No mixing of conventions, and the names are self-describing.
Two tools is on the thin side for a search/discovery server, even a focused one. Given the descriptions reference a companion content-reading tool (you-contents), the surface feels intentionally trimmed rather than well-scoped.
Both descriptions instruct the agent to read results with 'you-contents', but that tool is absent from the set, creating a dead end for the core workflow of turning snippets into page content. Search and discovery are covered, but the advertised retrieval lifecycle is incomplete.
Web scraping, search, crawling, structured extraction and research for AI agents.
Web search and any page as LLM-ready Markdown for AI agents. Free keyless tier, no signup.
Live web search for AI agents. $0.001/call, x402 on Base, no API key.
Agent-native search engine with live web research optimized for AI agents.
