Claude-skill-registry claude-agent-sdk-integration

Integrate Claude Agent SDK with You.com HTTP MCP server for Python and TypeScript. Use when developer mentions Claude Agent SDK, Anthropic Agent SDK, or integrating Claude with MCP tools.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/claude-agent-sdk-integration" ~/.claude/skills/majiayu000-claude-skill-registry-claude-agent-sdk-integration && rm -rf "$T"

manifest: skills/data/claude-agent-sdk-integration/SKILL.md

Integrate Claude Agent SDK with You.com MCP

Interactive workflow to set up Claude Agent SDK with You.com's HTTP MCP server.

Workflow

Ask: Language Choice
- Python or TypeScript?
If TypeScript - Ask: SDK Version
- v1 (stable, generator-based) or v2 (preview, send/receive pattern)?
- Note: v2 requires TypeScript 5.2+ for
```
await using
```
  support

Install Package

Python:
```
pip install claude-agent-sdk
```

TypeScript:

npm install @anthropic-ai/claude-agent-sdk

Ask: Environment Variables
- Using standard
```
YDC_API_KEY
```
  and
```
ANTHROPIC_API_KEY
```
  ?
- Or custom names?
- Have they set them?
- If NO: Guide to get keys:
  - YDC_API_KEY: https://you.com/platform/api-keys
  - ANTHROPIC_API_KEY: https://console.anthropic.com/settings/keys
Ask: File Location
- NEW file: Ask where to create and what to name
- EXISTING file: Ask which file to integrate into (add HTTP MCP config)

Create/Update File

For NEW files:

Use the complete template code from the "Complete Templates" section below
User can run immediately with their API keys set

For EXISTING files:

Add HTTP MCP server configuration to their existing code

Python configuration block:

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={
        "ydc": {
            "type": "http",
            "url": "https://api.you.com/mcp",
            "headers": {
                "Authorization": f"Bearer {os.getenv('YDC_API_KEY')}"
            }
        }
    },
    allowed_tools=[
        "mcp__ydc__you_search",
        "mcp__ydc__you_express",
        "mcp__ydc__you_contents"
    ]
)

TypeScript configuration block:

const options = {
  mcpServers: {
    ydc: {
      type: 'http' as const,
      url: 'https://api.you.com/mcp',
      headers: {
        Authorization: `Bearer ${process.env.YDC_API_KEY}`
      }
    }
  },
  allowedTools: [
    'mcp__ydc__you_search',
    'mcp__ydc__you_express',
    'mcp__ydc__you_contents'
  ]
};

Complete Templates

Use these complete templates for new files. Each template is ready to run with your API keys set.

Python Template (Complete Example)

"""
Claude Agent SDK with You.com HTTP MCP Server
Python implementation with async/await pattern
"""

import os
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

# Validate environment variables
ydc_api_key = os.getenv("YDC_API_KEY")
anthropic_api_key = os.getenv("ANTHROPIC_API_KEY")

if not ydc_api_key:
    raise ValueError(
        "YDC_API_KEY environment variable is required. "
        "Get your key at: https://you.com/platform/api-keys"
    )

if not anthropic_api_key:
    raise ValueError(
        "ANTHROPIC_API_KEY environment variable is required. "
        "Get your key at: https://console.anthropic.com/settings/keys"
    )


async def main():
    """
    Example: Search for AI news and get results from You.com MCP server
    """
    # Configure Claude Agent with HTTP MCP server
    options = ClaudeAgentOptions(
        mcp_servers={
            "ydc": {
                "type": "http",
                "url": "https://api.you.com/mcp",
                "headers": {"Authorization": f"Bearer {ydc_api_key}"},
            }
        },
        allowed_tools=[
            "mcp__ydc__you_search",
            "mcp__ydc__you_express",
            "mcp__ydc__you_contents",
        ],
        model="claude-sonnet-4-5-20250929",
    )

    # Query Claude with MCP tools available
    async for message in query(
        prompt="Search for the latest AI news from this week",
        options=options,
    ):
        # Handle different message types
        if message.type == "text":
            print(message.content)
        elif message.type == "tool_use":
            print(f"\n[Tool: {message.name}]")
            print(f"Input: {message.input}")
        elif message.type == "tool_result":
            print(f"Result: {message.content}")


if __name__ == "__main__":
    asyncio.run(main())

TypeScript v1 Template (Complete Example)

/**
 * Claude Agent SDK with You.com HTTP MCP Server
 * TypeScript v1 implementation with generator-based pattern
 */

import { query } from '@anthropic-ai/claude-agent-sdk';

// Validate environment variables
const ydcApiKey = process.env.YDC_API_KEY;
const anthropicApiKey = process.env.ANTHROPIC_API_KEY;

if (!ydcApiKey) {
  throw new Error(
    'YDC_API_KEY environment variable is required. ' +
      'Get your key at: https://you.com/platform/api-keys'
  );
}

if (!anthropicApiKey) {
  throw new Error(
    'ANTHROPIC_API_KEY environment variable is required. ' +
      'Get your key at: https://console.anthropic.com/settings/keys'
  );
}

/**
 * Example: Search for AI news and get results from You.com MCP server
 */
async function main() {
  // Query Claude with HTTP MCP configuration
  const result = query({
    prompt: 'Search for the latest AI news from this week',
    options: {
      mcpServers: {
        ydc: {
          type: 'http' as const,
          url: 'https://api.you.com/mcp',
          headers: {
            Authorization: `Bearer ${ydcApiKey}`,
          },
        },
      },
      allowedTools: [
        'mcp__ydc__you_search',
        'mcp__ydc__you_express',
        'mcp__ydc__you_contents',
      ],
      model: 'claude-sonnet-4-5-20250929',
    },
  });

  // Process messages as they arrive
  for await (const msg of result) {
    if (msg.type === 'text') {
      console.log(msg.content);
    } else if (msg.type === 'tool_use') {
      console.log(`\n[Tool: ${msg.name}]`);
      console.log(`Input: ${JSON.stringify(msg.input, null, 2)}`);
    } else if (msg.type === 'tool_result') {
      console.log(`Result: ${msg.content}`);
    }
  }
}

main().catch(console.error);

TypeScript v2 Template (Complete Example)

/**
 * Claude Agent SDK with You.com HTTP MCP Server
 * TypeScript v2 implementation with send/receive pattern
 * Requires TypeScript 5.2+ for 'await using' support
 */

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk';

// Validate environment variables
const ydcApiKey = process.env.YDC_API_KEY;
const anthropicApiKey = process.env.ANTHROPIC_API_KEY;

if (!ydcApiKey) {
  throw new Error(
    'YDC_API_KEY environment variable is required. ' +
      'Get your key at: https://you.com/platform/api-keys'
  );
}

if (!anthropicApiKey) {
  throw new Error(
    'ANTHROPIC_API_KEY environment variable is required. ' +
      'Get your key at: https://console.anthropic.com/settings/keys'
  );
}

/**
 * Example: Search for AI news and get results from You.com MCP server
 */
async function main() {
  // Create session with HTTP MCP configuration
  // 'await using' ensures automatic cleanup when scope exits
  await using session = unstable_v2_createSession({
    mcpServers: {
      ydc: {
        type: 'http' as const,
        url: 'https://api.you.com/mcp',
        headers: {
          Authorization: `Bearer ${ydcApiKey}`,
        },
      },
    },
    allowedTools: [
      'mcp__ydc__you_search',
      'mcp__ydc__you_express',
      'mcp__ydc__you_contents',
    ],
    model: 'claude-sonnet-4-5-20250929',
  });

  // Send message to Claude
  await session.send('Search for the latest AI news from this week');

  // Receive and process messages
  for await (const msg of session.receive()) {
    if (msg.type === 'text') {
      console.log(msg.content);
    } else if (msg.type === 'tool_use') {
      console.log(`\n[Tool: ${msg.name}]`);
      console.log(`Input: ${JSON.stringify(msg.input, null, 2)}`);
    } else if (msg.type === 'tool_result') {
      console.log(`Result: ${msg.content}`);
    }
  }
}

main().catch(console.error);

HTTP MCP Server Configuration

All templates use You.com's HTTP MCP server for simplicity:

Python:

mcp_servers={
    "ydc": {
        "type": "http",
        "url": "https://api.you.com/mcp",
        "headers": {
            "Authorization": f"Bearer {ydc_api_key}"
        }
    }
}

TypeScript:

mcpServers: {
  ydc: {
    type: 'http' as const,
    url: 'https://api.you.com/mcp',
    headers: {
      Authorization: `Bearer ${ydcApiKey}`
    }
  }
}

Benefits of HTTP MCP:

✅ No local installation required
✅ Stateless request/response model
✅ Always up-to-date with latest version
✅ Consistent across all environments
✅ Production-ready and scalable
✅ Works with existing HTTP infrastructure

Available You.com Tools

After configuration, Claude can use these tools:

mcp__ydc__you_search

Web and news search with filters:

```
query
```
: Search query string
```
freshness
```
: Filter by recency (day, week, month, year)
```
country
```
: Country code for localized results
```
count
```
: Number of results to return

mcp__ydc__you_express

Fast AI agent with optional web search:

```
input
```
: Query or instruction for the AI agent
```
tools
```
: Optional list of tools to use (e.g., ["search"])

mcp__ydc__you_contents

Web page content extraction:

```
urls
```
: Array of URLs to extract content from
```
formats
```
: Output formats - array of
```
"markdown"
```
,
```
"html"
```
, or
```
"metadata"
```
```
crawl_timeout
```
: Optional timeout in seconds (1-60)

Environment Variables

Both API keys are required:

# Add to your .env file or shell profile
export YDC_API_KEY="your-you-api-key-here"
export ANTHROPIC_API_KEY="your-anthropic-api-key-here"

Get your API keys:

You.com: https://you.com/platform/api-keys
Anthropic: https://console.anthropic.com/settings/keys

Validation Checklist

Before completing:

Package installed:

claude-agent-sdk

(Python) or

@anthropic-ai/claude-agent-sdk

(TypeScript)

Environment variables set:
```
YDC_API_KEY
```
and
```
ANTHROPIC_API_KEY
```
Template copied or configuration added to existing file
HTTP MCP server configured (
```
https://api.you.com/mcp
```
)
Authorization header includes
```
Bearer ${YDC_API_KEY}
```
Allowed tools list includes You.com tools
File is executable (Python) or can be compiled (TypeScript)
Ready to test with example query

Testing Your Integration

Python:

python your-file.py

TypeScript:

# With tsx (recommended for quick testing)
npx tsx your-file.ts

# Or compile and run
tsc your-file.ts && node your-file.js

Common Issues

<details> <summary>Cannot find module @anthropic-ai/claude-agent-sdk</summary>

Install the package:

# NPM
npm install @anthropic-ai/claude-agent-sdk

# Bun
bun add @anthropic-ai/claude-agent-sdk

# Yarn
yarn add @anthropic-ai/claude-agent-sdk

# pnpm
pnpm add @anthropic-ai/claude-agent-sdk

</details> <details> <summary>YDC_API_KEY environment variable is required</summary>

Set your You.com API key:

export YDC_API_KEY="your-api-key-here"

Get your key at: https://you.com/platform/api-keys

</details> <details> <summary>ANTHROPIC_API_KEY environment variable is required</summary>

Set your Anthropic API key:

export ANTHROPIC_API_KEY="your-api-key-here"

Get your key at: https://console.anthropic.com/settings/keys

</details> <details> <summary>MCP connection fails with 401 Unauthorized</summary>

Verify your YDC_API_KEY is valid:

Check the key at https://you.com/platform/api-keys
Ensure no extra spaces or quotes in the environment variable
Verify the Authorization header format:
```
Bearer ${YDC_API_KEY}
```

</details> <details> <summary>Tools not available or not being called</summary>

Ensure

allowedTools

includes the correct tool names:

```
mcp__ydc__you_search
```
(not
```
you_search
```
)
```
mcp__ydc__you_express
```
(not
```
you_express
```
)
```
mcp__ydc__you_contents
```
(not
```
you_contents
```
)

Tool names must include the

mcp__ydc__

prefix.

</details> <details> <summary>TypeScript error: Cannot use 'await using'</summary>

The v2 SDK requires TypeScript 5.2+ for

await using

syntax.

Solution 1: Update TypeScript

npm install -D typescript@latest

Solution 2: Use manual cleanup

const session = unstable_v2_createSession({ /* options */ });
try {
  await session.send('Your query');
  for await (const msg of session.receive()) {
    // Process messages
  }
} finally {
  session.close();
}

Solution 3: Use v1 SDK instead Choose v1 during setup for broader TypeScript compatibility.

</details>

Advanced: MCP Server Development Patterns

For developers creating custom MCP tools or contributing to @youdotcom-oss/mcp:

Schema Design

Always use Zod for input/output validation:

export const MyToolInputSchema = z.object({
  query: z.string().min(1).describe("Search query"),
  limit: z.number().optional().describe("Max results"),
});

Why this pattern?

Zod provides runtime validation and TypeScript types
```
.describe()
```
adds documentation for MCP tool parameters
Schema validation catches invalid inputs before API calls

Error Handling

Always use try/catch with typed error handling:

try {
  const response = await apiCall();
  return formatResponse(response);
} catch (err: unknown) {
  const errorMessage = err instanceof Error ? err.message : String(err);
  await logger({ level: "error", data: `API call failed: ${errorMessage}` });
  return {
    content: [{ type: "text", text: `Error: ${errorMessage}` }],
    isError: true,
  };
}

Why this pattern?

MCP tools must return structured responses, never throw
```
err: unknown
```
ensures type safety in catch blocks
User-friendly error messages in
```
content
```

Response Format

Return both

content

and

structuredContent

return {
  content: [{ type: "text", text: formattedText }],
  structuredContent: responseData,
};

Why this pattern?

```
content
```
provides human-readable text for display
```
structuredContent
```
provides machine-readable data
MCP clients can choose which format to use

Additional Resources

You.com MCP Server: https://documentation.you.com/developer-resources/mcp-server
Claude Agent SDK (Python): https://platform.claude.com/docs/en/agent-sdk/python
Claude Agent SDK (TypeScript v1): https://platform.claude.com/docs/en/agent-sdk/typescript
Claude Agent SDK (TypeScript v2): https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview
API Keys:
- You.com: https://you.com/platform/api-keys
- Anthropic: https://console.anthropic.com/settings/keys

Claude-skill-registry claude-agent-sdk-integration

Integrate Claude Agent SDK with You.com MCP

Workflow

Complete Templates

Python Template (Complete Example)

TypeScript v1 Template (Complete Example)

TypeScript v2 Template (Complete Example)

HTTP MCP Server Configuration

Available You.com Tools

`mcpydcyou_search`

`mcpydcyou_express`

`mcpydcyou_contents`

Environment Variables

Validation Checklist

Testing Your Integration

Common Issues

Advanced: MCP Server Development Patterns

Schema Design

Error Handling

Response Format

Additional Resources