# How to Integrate Context7 with Custom AI SDK Implementations

> Integrate Context7 with custom AI SDKs by initializing the client and adapting existing wrappers. Learn how to seamlessly connect Context7 to your AI projects.

- Repository: [Upstash/context7](https://github.com/upstash/context7)
- Tags: how-to-guide
- Published: 2026-02-19

---

**You can integrate Context7 into any custom AI SDK by initializing the `@upstash/context7-sdk` client and wrapping the `searchLibrary` and `getContext` methods inside your framework's tool interface, or by adapting the official Vercel AI SDK wrappers found in [`resolve-library-id.ts`](https://github.com/upstash/context7/blob/main/resolve-library-id.ts) and [`query-docs.ts`](https://github.com/upstash/context7/blob/main/query-docs.ts).**

Integrating live, version-specific library documentation into custom AI workflows requires a reliable bridge between the Context7 REST API and your SDK's tool-calling interface. The Context7 repository provides two complementary packages that make this straightforward: a lightweight HTTP client for direct API access, and thin adapter wrappers that demonstrate the exact pattern needed to plug into any orchestration layer.

## Core Packages for Context7 Integration

The Context7 ecosystem supplies two npm packages that serve different integration needs:

- **`@upstash/context7-sdk`** – The foundational HTTP client that exposes `searchLibrary` and `getContext` methods. Import the `Context7` class directly to make raw API calls within your custom tooling logic.
- **`@upstash/context7-tools-ai-sdk`** – Reference implementations showing how to expose Context7 functionality as AI SDK-compatible tools. These wrappers are approximately 70 lines each and serve as copy-paste templates for custom SDKs.

When building a custom integration, you typically import the base SDK and implement your own adapter layer, using the official wrappers as a reference for error handling and parameter mapping.

## Direct SDK Integration Pattern

To integrate Context7 with a custom AI SDK implementation, follow this three-step pattern: initialize the client, resolve the library identifier, and retrieve the documentation context.

### Initialize the Context7 Client

The `Context7` class automatically reads the `CONTEXT7_API_KEY` environment variable if you do not provide an `apiKey` explicitly in the constructor.

```typescript
import { Context7 } from "@upstash/context7-sdk";

const client = new Context7({ apiKey: process.env.CONTEXT7_API_KEY });

```

### Resolve the Library and Fetch Context

Most AI SDKs expect a tool function that accepts user input and returns a string or structured JSON. Inside this function, call `searchLibrary` to find the best-matching library ID, then pass that ID to `getContext` to retrieve the documentation.

```typescript
async function docsTool(userPrompt: string, libName: string): Promise<string> {
  // 1️⃣ Resolve the library ID
  const libraries = await client.searchLibrary(userPrompt, libName, { 
    type: "txt" 
  });
  
  if (!libraries?.length) {
    throw new Error(`No Context7 library found for "${libName}"`);
  }

  // 2️⃣ Pull documentation for the most relevant match
  const docs = await client.getContext(userPrompt, libraries[0].id, { 
    type: "txt" 
  });

  // 3️⃣ Format for your AI SDK (example: concatenated text)
  return docs.map((d) => `${d.title}\n${d.content}`).join("\n\n");
}

```

The `searchLibrary` method ranks libraries by relevance to the user prompt, while `getContext` returns an array of objects containing `title` and `content` fields that you can reshape to match your SDK's expected return type.

## Creating Custom AI SDK Wrappers

If your AI SDK requires a specific tool signature—such as LangChain's `Tool` interface or a custom agent loop—you can copy the adapter pattern from the official Vercel AI SDK wrappers and modify the return format.

### Reference Implementation Locations

The official wrappers demonstrate the exact structure needed:

- **[`packages/tools-ai-sdk/src/tools/resolve-library-id.ts`](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/resolve-library-id.ts)** – Implements `resolveLibraryId`, wrapping `client.searchLibrary` to return raw search results with error handling.
- **[`packages/tools-ai-sdk/src/tools/query-docs.ts`](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/query-docs.ts)** – Implements `queryDocs`, wrapping `client.getContext` to return documentation snippets.

Both files are roughly 70 lines and show how to wire the Zod schema, description, and execution logic expected by tool-calling frameworks.

### Custom Wrapper Example

Below is a framework-agnostic implementation that could be registered as a LangChain tool, an OpenAI function, or any custom orchestration layer:

```typescript
// custom-context7-tool.ts
import { Context7 } from "@upstash/context7-sdk";

const client = new Context7(); // Uses CONTEXT7_API_KEY env var

export async function fetchContext7Docs(
  userPrompt: string,
  libName: string
): Promise<string> {
  const libraries = await client.searchLibrary(userPrompt, libName, { 
    type: "txt" 
  });

  if (!libraries?.length) {
    return `No documentation found for library: ${libName}`;
  }

  const docs = await client.getContext(userPrompt, libraries[0].id, { 
    type: "txt" 
  });

  return docs.map((d) => `${d.title}\n${d.content}`).join("\n\n");
}

```

This pattern reuses a single `Context7` instance across calls, handles missing libraries gracefully, and concatenates documentation chunks into a format suitable for LLM context windows.

## Mapping Wrapper Functions to SDK Methods

When adapting the official wrappers to your custom AI SDK, map the tool functions to their underlying SDK calls as follows:

| Wrapper Function | Source File | Core SDK Method | Purpose |
|-----------------|-------------|-----------------|---------|
| **resolveLibraryId** | [`packages/tools-ai-sdk/src/tools/resolve-library-id.ts`](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/resolve-library-id.ts) | `client.searchLibrary(query, libraryName, { type: "txt" })` | Resolves a human-readable library name to a Context7 library ID |
| **queryDocs** | [`packages/tools-ai-sdk/src/tools/query-docs.ts`](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/query-docs.ts) | `client.getContext(query, libraryId, { type: "txt" })` | Retrieves documentation snippets using the resolved library ID |

Both wrappers handle the `json` versus `txt` response type conversion and implement fallback logic for environment variable configuration, which you should preserve when copying the pattern into your own codebase.

## Summary

- **Install the base SDK** – Use `@upstash/context7-sdk` to access the `Context7` class and its `searchLibrary` and `getContext` methods.
- **Initialize once** – Create a single client instance that reads from the `CONTEXT7_API_KEY` environment variable.
- **Copy the adapter pattern** – Reference the implementations in [`packages/tools-ai-sdk/src/tools/resolve-library-id.ts`](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/resolve-library-id.ts) and [`query-docs.ts`](https://github.com/upstash/context7/blob/main/query-docs.ts) to see how to structure tool functions for your specific AI SDK.
- **Handle the two-step flow** – Always resolve the library ID first via `searchLibrary`, then fetch documentation via `getContext`, converting the response format to match your framework's requirements.

## Frequently Asked Questions

### How do I handle authentication when integrating Context7 with a custom AI SDK?

The `Context7` class constructor accepts an `apiKey` option. If omitted, it automatically falls back to the `CONTEXT7_API_KEY` environment variable. Store your API key in this environment variable and initialize the client with `new Context7()` to avoid hardcoding credentials in your custom implementation.

### Can I use the official Vercel AI SDK wrappers with other frameworks like LangChain?

Yes. While the `@upstash/context7-tools-ai-sdk` package is designed for the Vercel AI SDK (`ai` package), the individual wrapper files in `packages/tools-ai-sdk/src/tools/` are thin enough to be copied and adapted. Modify the return statements and parameter schemas in [`resolve-library-id.ts`](https://github.com/upstash/context7/blob/main/resolve-library-id.ts) and [`query-docs.ts`](https://github.com/upstash/context7/blob/main/query-docs.ts) to match LangChain's `Tool` interface or your custom SDK's expected shape.

### What response format does the Context7 SDK return?

The `searchLibrary` method returns an array of library objects containing metadata and IDs. The `getContext` method returns an array of documentation chunks, where each element is an object with `title` and `content` properties. When integrating with custom AI SDKs, you typically concatenate these chunks into a single string or map them to your framework's preferred document structure.

### Is there a performance benefit to reusing the Context7 client instance?

Yes. Initialize the `Context7` client once and reuse it across multiple tool calls within your application lifecycle. The client handles HTTP connection pooling and header management internally, making repeated calls to `searchLibrary` and `getContext` more efficient than creating a new instance per request.