How to Use the Kavita (eBook/Manga) MCP in Pydantic AI

Q: Can my Pydantic AI agent check if my Kavita (eBook/Manga) token is still valid?

Yes, the agent calls checkauthkeyexpires to verify the expiration timestamp. If the token has expired, it triggers authenticate to establish a fresh session before executing any scans.

Ensure type-safe library updates on your Kavita server using this MCP Server with Pydantic AI python agents.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Kavita (eBook/Manga) MCP to Pydantic AI

Create your Vinkius account to connect Kavita (eBook/Manga) to Pydantic AI 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 Kavita (eBook/Manga) with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe scans with Pydantic AI validation

The `scan_library` tool executes with strict schema validation to ensure your library IDs are formatted correctly before hitting the Kavita API. If your agent attempts to pass an invalid ID, the framework catches the error instantly at runtime. This prevents malformed requests from reaching your media server. You get clean, predictable execution every time your agent updates your manga collection.

Strict session state management

The `authenticate` and `check_authkey_expires` tools return validated data structures that your agent uses to track connection health. Every token and expiration date maps to a strict Pydantic model. If the Kavita API returns unexpected payload formats, your agent fails loudly instead of corrupting your session state. This guarantees your authentication pipeline remains completely reliable.

Robust error handling for global scans

This MCP Server exposes `scan_all_libraries` with clear return types so your agent knows exactly when a full update starts. The response is parsed and validated against your defined schemas. Your agent uses this structured feedback to coordinate downstream tasks, like notifying your reading group when the scan completes. No silent failures, no guesswork.

Setup guide

Set up Kavita (eBook/Manga) MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "kavita-ebookmanga-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Kavita (eBook/Manga) tools.",
)

result = await agent.run("List recent Kavita (eBook/Manga) transactions")
print(result.output)

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 Kavita. 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 Kavita (eBook/Manga) 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 Kavita (eBook/Manga) MCP in Pydantic AI

Use the unified toolset class pointing to your HTTP server URL and pass it to your agent's toolsets parameter. Avoid the deprecated HTTP server classes to ensure clean runtime validation.

The framework catches the API error and validates the failure response against its internal models. Your agent receives a structured error, allowing it to retry the library scan or log the issue without crashing.

Yes, this server supports both streamable HTTP and SSE transports. You can configure your toolset to use either protocol depending on how your external Kavita instance is hosted.

Yes, the agent calls `check_authkey_expires` to verify the expiration timestamp. If the token has expired, it triggers `authenticate` to establish a fresh session before executing any scans.

Your Kavita API keys and JWT tokens are processed exclusively in-memory within an ephemeral V8 sandbox. They are never logged, cached globally, or exposed to the LLM, keeping your library's access credentials entirely private.

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