How to Use the Gutendex MCP in OpenAI Agents SDK

Q: How do I initialize the Gutendex MCP Server in OpenAI Agents SDK?

Install the SDK using pip, then use MCPServerStreamableHttp to connect to the server URL. Pass this instance in the mcpservers list when initializing your Agent.

Q: Can my OpenAI Agents SDK pipeline search books by language using Gutendex?

Yes, the listbooks tool accepts two-letter ISO language codes like "en" or "fr" to filter search results. Your agent can combine this with author year ranges or topics to narrow down the list.

Q: How does OpenAI Agents SDK handle pagination with Gutendex?

The listbooks tool returns paginated results, and your agent can pass the next-page URL directly to getbooksbyurl to continue reading. This setup prevents context window overflow by fetching books in controlled batches.

Feed 70,000+ public domain ebooks straight to your OpenAI Agents SDK pipelines with zero API key configuration.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Gutendex MCP to OpenAI Agents SDK

Create your Vinkius account to connect Gutendex to OpenAI Agents SDK and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Gutendex with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Filter and query Gutenberg books dynamically

The `list_books` tool exposes the entire Project Gutenberg catalog to your agents, allowing searches by author, title, topic, language, and publication year. Your agent can run precise queries to find specific texts, retrieve their download counts, and rank them by popularity. This tool feeds metadata directly into your agent's context, letting it decide which texts to parse for analysis. By passing this tool to your OpenAI Agents SDK setup, you let your models discover literature without hardcoding search parameters.

Fetch full book metadata with OpenAI Agents SDK

The `get_book` tool fetches the title, authors, subjects, bookshelves, and download formats for any Project Gutenberg ID. It extracts raw download links for formats like EPUB, Kindle, and plain text, bypassing the need for manual web scraping. Your agent uses this tool to grab specific texts like Frankenstein (ID 84) or Moby Dick (ID 2701) for downstream processing. The OpenAI dashboard tracks these tool calls, giving you full visibility into what your agents retrieve.

Resolve raw Gutenberg links via MCP Server

The `get_books_by_url` tool resolves standard Project Gutenberg URLs into structured book metadata. If your agent encounters a raw web link in its prompt or database, it calls this tool to extract the underlying book ID and details. This MCP Server tool handles the translation between raw web URLs and structured JSON payloads. It ensures your agent never gets stuck on external links and can always fetch the exact text format it needs.

Setup guide

Set up Gutendex MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Gutendex tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Gutendex tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Gutendex tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Gutendex Agent",
            instructions="You have access to Gutendex tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Gutendex. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Gutendex now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Gutendex MCP in OpenAI Agents SDK

Install the SDK using pip, then use `MCPServerStreamableHttp` to connect to the server URL. Pass this instance in the `mcp_servers` list when initializing your Agent.

Yes, the `list_books` tool accepts two-letter ISO language codes like "en" or "fr" to filter search results. Your agent can combine this with author year ranges or topics to narrow down the list.

No, the Gutendex API is free and public, meaning this integration works out of the box without any authentication keys. You only need the connection token provided by Vinkius.

The `list_books` tool returns paginated results, and your agent can pass the next-page URL directly to `get_books_by_url` to continue reading. This setup prevents context window overflow by fetching books in controlled batches.

This server only handles public ebook metadata, search queries, and Gutenberg URLs. No personal user data or private files are ever sent to the Gutendex API, and Vinkius runs the server in an isolated sandbox.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript