ydc-claude-agent-sdk-integration skill

---
name: ydc-claude-agent-sdk-integration
description: 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.
license: MIT
compatibility: Python 3.10+ or TypeScript 5.2+, Node.js 24+ or Bun 1.3+
allowed-tools: Read Write Edit Bash(pip:install) Bash(npm:install) Bash(bun:add)
metadata:
  author: youdotcom-oss
  category: sdk-integration
  version: "1.1.0"
  keywords: claude,anthropic,claude-agent-sdk,agent-sdk,mcp,you.com,integration,http-mcp,web-search,python,typescript
---

# Integrate Claude Agent SDK with You.com MCP

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

## Workflow

1. **Ask: Language Choice**
   * Python or TypeScript?

2. **If TypeScript - Ask: SDK Version**
   * v1 (stable, generator-based) or v2 (preview, send/receive pattern)?
   * ⚠️ **v2 Stability Warning**: The v2 SDK is in **preview** and uses `unstable_v2_*` APIs that may change. Only use v2 if you need the send/receive pattern and accept potential breaking changes. For production use, prefer v1.
   * Note: v2 requires TypeScript 5.2+ for `await using` support

3. **Install Package**
   * Python: `pip install claude-agent-sdk`
   * TypeScript: `npm install @anthropic-ai/claude-agent-sdk`

4. **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

5. **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)

6. **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:
     ```python
     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_contents"
         ]
     )
     ```

   * TypeScript configuration block:
     ```typescript
     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_contents'
       ]
     };
     ```

## Alternative: Install as Claude Code Skill

Instead of manually creating files, you can install this skill directly into Claude Code for easy access:

**Installation:**
```bash
npx skills add youdotcom-oss/agent-skills/ydc-claude-agent-sdk-integration
```

**Important:** After installation, you must configure Claude Code to load skills from the filesystem. Add this to your Claude Code settings:

```json
{
  "setting_sources": ["project"]
}
```

**How it works:**
- Skills are installed to `~/.claude/skills/`
- Claude Code loads skills from this directory when `setting_sources` includes `"project"`
- The skill becomes available via slash commands (e.g., `/ydc-claude-agent-sdk-integration`)
- This provides an interactive workflow without manual file creation

**When to use this approach:**
- You want Claude Code to guide you through the integration interactively
- You prefer not to manually create template files
- You want the skill available across multiple projects

**When to use manual templates (below):**
- You need to customize the code extensively
- You're integrating into existing codebases
- You don't use Claude Code

## Complete Templates

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

### Python Template (Complete Example)

```python
"""
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_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
        # Messages from the SDK are typed objects with specific attributes
        if hasattr(message, "result"):
            # Final result message with the agent's response
            print(message.result)


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

### TypeScript v1 Template (Complete Example)

```typescript
/**
 * 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_contents',
      ],
      model: 'claude-sonnet-4-5-20250929',
    },
  });

  // Process messages as they arrive
  for await (const msg of result) {
    // Handle different message types
    // Check for final result message
    if ('result' in msg) {
      // Final result message with the agent's response
      console.log(msg.result);
    }
  }
}

main().catch(console.error);
```

### TypeScript v2 Template (Complete Example)

⚠️ **Preview API Warning**: This template uses `unstable_v2_createSession` which is a **preview API** subject to breaking changes. The v2 SDK is not recommended for production use. Consider using the v1 template above for stable, production-ready code.

```typescript
/**
 * Claude Agent SDK with You.com HTTP MCP Server
 * TypeScript v2 implementation with send/receive pattern
 * Requires TypeScript 5.2+ for 'await using' support
 * WARNING: v2 is a preview API and may have breaking changes
 */

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_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()) {
    // Handle different message types
    // Check for final result message
    if ('result' in msg) {
      // Final result message with the agent's response
      console.log(msg.result);
    }
  }
}

main().catch(console.error);
```

## HTTP MCP Server Configuration

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

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

**TypeScript:**
```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 discover and use:
- `mcp__ydc__you_search` - Web and news search
- `mcp__ydc__you_contents` - Web page content extraction

## Environment Variables

Both API keys are required:

```bash
# 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:**
```bash
python your-file.py
```

**TypeScript:**
```bash
# 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><strong>Cannot find module @anthropic-ai/claude-agent-sdk</strong></summary>

Install the package:

```bash
# 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><strong>YDC_API_KEY environment variable is required</strong></summary>

Set your You.com API key:

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

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

</details>

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

Set your Anthropic API key:

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

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

</details>

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

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

</details>

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

Ensure `allowedTools` includes the correct tool names:
- `mcp__ydc__you_search` (not `you_search`)
- `mcp__ydc__you_contents` (not `you_contents`)

Tool names must include the `mcp__ydc__` prefix.

</details>

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

The v2 SDK requires TypeScript 5.2+ for `await using` syntax.

**Solution 1: Update TypeScript**
```bash
npm install -D typescript@latest
```

**Solution 2: Use manual cleanup**
```typescript
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>



## 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