Skip to main content

​
Overview

This is a community-maintained integration developed by GhouI. For official integrations, see Vercel AI SDK or use the Valyu API directly.
The Valyu Claude Agent SDK integration enables AI agents built with Anthropic’s Claude Agent SDK to access real-time web data and specialized knowledge bases through powerful search capabilities. This integration provides domain-specific search tools using the Model Context Protocol (MCP), making it easy to build intelligent agents that can search academic papers, financial data, patents, and more. The integration includes search tools for:
  • Web Search: Real-time information, news, and current events
  • Finance Search: Stock prices, earnings reports, SEC filings, and financial metrics
  • Paper Search: Academic research from arXiv and scholarly databases
  • Bio Search: Biomedical literature, PubMed articles, and clinical trials
  • Patent Search: Patent databases and prior art research
  • SEC Search: Regulatory documents (10-K, 10-Q, 8-K filings)
  • Economics Search: Labor statistics, Federal Reserve data, World Bank indicators
  • Company Research: Comprehensive intelligence reports with synthesized data

​
Installation

Clone the community-maintained repository and install dependencies: 
git clone https://github.com/GhouI/valyu-claude-agent-sdk.git
cd valyu-claude-agent-sdk
The --legacy-peer-deps flag is required due to Zod version compatibility requirements.
Configure credentials by adding your Valyu API key to a .env file: 
VALYU_API_KEY=your-valyu-api-key-here
The package automatically reads this environment variable.

Free Credits

Get your API key with $10 credit from the Valyu Platform.

​
Basic Usage

​
Web Search Example

Search for real-time information, news, and current events: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuWebSearchServer } from "./tools/index.js";

async function webSearchExample() {
  for await (const message of query({
    prompt: "What are the latest developments in AI technology?",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-web-search__web_search"],
      mcpServers: {
        "valyu-web-search": valyuWebSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await webSearchExample();

​
Finance Search Example

Access stock prices, earnings reports, and financial data: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuFinanceSearchServer } from "./tools/index.js";

async function financeSearchExample() {
  for await (const message of query({
    prompt: "What is the current stock price of NVIDIA and their recent earnings?",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-finance-search__finance_search"],
      mcpServers: {
        "valyu-finance-search": valyuFinanceSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await financeSearchExample();

​
Academic Paper Search Example

Search for scholarly articles and research publications: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuPaperSearchServer } from "./tools/index.js";

async function paperSearchExample() {
  for await (const message of query({
    prompt: "Find recent papers on transformer architecture improvements",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-paper-search__paper_search"],
      mcpServers: {
        "valyu-paper-search": valyuPaperSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await paperSearchExample();

​
Company Research Example

Get comprehensive intelligence reports about companies: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import { valyuCompanyResearchServer } from "./tools/index.js";

async function companyResearchExample() {
  for await (const message of query({
    prompt: "Give me a comprehensive report on OpenAI including leadership, products, and funding",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-company-research__company_research"],
      mcpServers: {
        "valyu-company-research": valyuCompanyResearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await companyResearchExample();

​
Advanced Configuration

​
Custom Bio Search Parameters

The bioSearch tool supports advanced configuration for specialized searches: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import { createBioSearchServer } from "./tools/index.js";

async function bioSearchWithParamsExample() {
  const customBioSearchServer = createBioSearchServer({
    searchType: "proprietary", // Focus on academic datasets
    maxNumResults: 10,
    includedSources: ["pubmed", "clinicaltrials.gov"],
    maxPrice: 30.0,
    relevanceThreshold: 0.7,
    category: "biomedical",
  });

  for await (const message of query({
    prompt: "Find clinical trials for CRISPR gene therapy",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: ["mcp__valyu-bio-search__bio_search"],
      mcpServers: {
        "valyu-bio-search": customBioSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await bioSearchWithParamsExample();

​
Multi-Tool Agent

Combine multiple search tools in a single agent: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import {
  valyuWebSearchServer,
  valyuFinanceSearchServer,
  valyuPaperSearchServer,
} from "./tools/index.js";

async function multiToolAgent() {
  for await (const message of query({
    prompt: "Research the impact of AI on financial markets, including recent news and academic papers",
    options: {
      model: "claude-sonnet-4-5",
      allowedTools: [
        "mcp__valyu-web-search__web_search",
        "mcp__valyu-finance-search__finance_search",
        "mcp__valyu-paper-search__paper_search",
      ],
      mcpServers: {
        "valyu-web-search": valyuWebSearchServer,
        "valyu-finance-search": valyuFinanceSearchServer,
        "valyu-paper-search": valyuPaperSearchServer,
      },
    },
  })) {
    if (message.type === "assistant") {
      const textContent = message.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(textContent);
    }
  }
}

await multiToolAgent();

​
All Available Search Tools

Real-time information, news, and current events from the web. 
import { valyuWebSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-web-search__web_search"
// Server key: "valyu-web-search"
Stock prices, earnings reports, SEC filings, and financial metrics. 
import { valyuFinanceSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-finance-search__finance_search"
// Server key: "valyu-finance-search"
Academic research from arXiv, bioRxiv, medRxiv, and PubMed. 
import { valyuPaperSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-paper-search__paper_search"
// Server key: "valyu-paper-search"
Biomedical literature, PubMed articles, and clinical trials. 
import { valyuBioSearchServer, createBioSearchServer } from "./tools/index.js";

// Default server
// Tool name: "mcp__valyu-bio-search__bio_search"
// Server key: "valyu-bio-search"

// Or create custom server with parameters
const customServer = createBioSearchServer({ /* options */ });
Patent databases and prior art research. 
import { valyuPatentSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-patent-search__patent_search"
// Server key: "valyu-patent-search"
SEC regulatory documents including 10-K, 10-Q, and 8-K filings. 
import { valyuSecSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-sec-search__sec_search"
// Server key: "valyu-sec-search"
Labor statistics (BLS), Federal Reserve (FRED), and World Bank data. 
import { valyuEconomicsSearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-economics-search__economics_search"
// Server key: "valyu-economics-search"

​
8. Company Research

Comprehensive intelligence reports with synthesized data from multiple sources. 
import { valyuCompanyResearchServer } from "./tools/index.js";

// Tool name: "mcp__valyu-company-research__company_research"
// Server key: "valyu-company-research"

​
Best Practices

​
1. Choose the Right Search Tool

Use specialized search tools for better results: 
// ❌ Bad: Using web search for financial data
const webResults = await query({
  prompt: "What is Apple's stock price?",
  options: {
    allowedTools: ["mcp__valyu-web-search__web_search"],
    mcpServers: { "valyu-web-search": valyuWebSearchServer },
  },
});

// ✅ Good: Using finance search for financial data
const financeResults = await query({
  prompt: "What is Apple's stock price?",
  options: {
    allowedTools: ["mcp__valyu-finance-search__finance_search"],
    mcpServers: { "valyu-finance-search": valyuFinanceSearchServer },
  },
});

​
2. Cost Optimization

Control costs using custom parameters: 
import { createBioSearchServer } from "./tools/index.js";

// For quick lookups, limit results and set max price
const quickSearch = createBioSearchServer({
  maxNumResults: 3,
  maxPrice: 15.0,
  relevanceThreshold: 0.6,
});

// For comprehensive research, allow more results
const deepSearch = createBioSearchServer({
  maxNumResults: 20,
  maxPrice: 50.0,
  relevanceThreshold: 0.5,
});

​
3. Error Handling

Always wrap queries in try-catch blocks: 
async function safeSearch() {
  try {
    for await (const message of query({
      prompt: "Search query here",
      options: {
        model: "claude-sonnet-4-5",
        allowedTools: ["mcp__valyu-web-search__web_search"],
        mcpServers: { "valyu-web-search": valyuWebSearchServer },
      },
    })) {
      if (message.type === "assistant") {
        const textContent = message.content
          .filter((block) => block.type === "text")
          .map((block) => block.text)
          .join("\n");
        console.log(textContent);
      }
    }
  } catch (error) {
    console.error("Search failed:", error);
    // Handle fallback or retry logic
  }
}

​
4. Source Filtering

Use includedSources to focus on specific data sources: 
const academicBioSearch = createBioSearchServer({
  searchType: "proprietary",
  includedSources: ["pubmed", "clinicaltrials.gov"],
  maxNumResults: 10,
  relevanceThreshold: 0.7,
});

​
5. Combining Multiple Tools

Allow agents to use multiple search tools for comprehensive research: 
// Comprehensive research combining web, finance, and company data
for await (const message of query({
  prompt: "Analyze Nvidia's market position and competitive landscape",
  options: {
    model: "claude-sonnet-4-5",
    allowedTools: [
      "mcp__valyu-web-search__web_search",
      "mcp__valyu-finance-search__finance_search",
      "mcp__valyu-company-research__company_research",
    ],
    mcpServers: {
      "valyu-web-search": valyuWebSearchServer,
      "valyu-finance-search": valyuFinanceSearchServer,
      "valyu-company-research": valyuCompanyResearchServer,
    },
  },
})) {
  // Handle messages
}

​
API Reference

​
Bio Search Configuration Parameters

The createBioSearchServer() function accepts the following configuration options:
  • searchType: "proprietary" or "web" - Type of search to perform (default: "proprietary")
  • maxNumResults: Number - Maximum number of results to return (default: 10)
  • includedSources: Array of strings - Specific data sources to include (e.g., ["pubmed", "clinicaltrials.gov"])
  • maxPrice: Number - Maximum cost in dollars (CPM-based pricing, default: 30.0)
  • relevanceThreshold: Number - Minimum relevance score (0.0-1.0, default: 0.5)
  • category: String - Search category to focus on (e.g., "biomedical")

​
Query Options

All search examples use the Claude Agent SDK query() function with the following structure: 
query({
  prompt: string,              // Natural language query
  options: {
    model: string,             // Claude model (e.g., "claude-sonnet-4-5")
    allowedTools: string[],    // MCP tool identifiers
    mcpServers: {              // MCP server configuration
      [key: string]: MCPServer
    },
    cwd?: string,              // Current working directory (optional)
  },
})

​
MCP Tool Identifiers

Each search tool has a specific identifier format: 
mcp__valyu-{tool-name}__{tool_name}
Examples:
  • mcp__valyu-web-search__web_search
  • mcp__valyu-finance-search__finance_search
  • mcp__valyu-paper-search__paper_search
  • mcp__valyu-bio-search__bio_search
  • mcp__valyu-patent-search__patent_search
  • mcp__valyu-sec-search__sec_search
  • mcp__valyu-economics-search__economics_search
  • mcp__valyu-company-research__company_research

​
Additional Resources

GitHub Repository

Community-maintained Claude Agent SDK integration source code

API Reference

Complete Valyu API documentation

Claude Agent SDK

Official Anthropic Claude Agent SDK

Get API Key

Sign up for free $10 credit

​
Support

This is a community-maintained integration. For issues or contributions: