How to Use the GitBook MCP in Pydantic AI

Q: Does Pydantic AI enforce schemas on GitBook tool calls?

Yes, every response from getpage or listspaces is validated against a Pydantic model. If the API returns something unexpected, the agent raises a validation error immediately. This prevents silent failures in your documentation agent.

Q: How do I list GitBook pages in Pydantic AI?

You use the listpages tool, which returns a structured list of page metadata. Pydantic AI validates this list against your model, making it safe to iterate through your doc structure.

Q: Can I use Pydantic AI to audit GitBook content?

You can build an auditing loop that uses listpages and getpage to check every document. The validation ensures that your auditing logic always receives the data in the format it expects. It makes finding stale docs much more reliable.

Strictly typed documentation interaction for Pydantic AI and GitBook.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect GitBook MCP to Pydantic AI

Create your Vinkius account to connect GitBook 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 GitBook with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe GitBook page retrieval

The `get_page` tool returns data that is immediately validated against your Pydantic models. If the schema shifts, your agent fails fast, preventing corrupt data from entering your pipeline. You can use `list_spaces` to fetch all available spaces and cast them into your defined types. This gives you a predictable structure for your documentation navigation.

Validated search results

Your agent uses `search_content` to find answers, and the output is checked against your model definitions. This keeps your search results consistent and predictable. Pair this with `get_page` to pull the full content. Because the response is validated, you know exactly what fields are available to your agent logic.

Organization and collection management

The `list_organizations` tool provides a list of your teams that is parsed into a Pydantic object. This ensures your agent is always talking to the correct account. Follow up with `list_collections` to categorize your docs. Since every tool response is validated, your agent will never hallucinate fields or structure that isn't there.

Setup guide

Set up GitBook 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": {
        "gitbook-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent GitBook 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 GitBook. 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 GitBook 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 GitBook MCP in Pydantic AI

Yes, every response from `get_page` or `list_spaces` is validated against a Pydantic model. If the API returns something unexpected, the agent raises a validation error immediately. This prevents silent failures in your documentation agent.

You use the `list_pages` tool, which returns a structured list of page metadata. Pydantic AI validates this list against your model, making it safe to iterate through your doc structure.

You can build an auditing loop that uses `list_pages` and `get_page` to check every document. The validation ensures that your auditing logic always receives the data in the format it expects. It makes finding stale docs much more reliable.

The server runs in an isolated V8 sandbox and communicates over a secure HTTP or SSE channel. It doesn't persist any session data, ensuring your documentation access remains private.

It only accesses your public and private documentation content, page hierarchies, and space metadata. It is restricted to read-only operations, so your actual documentation files cannot be modified or deleted.

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