How to Use the Substack MCP in Pydantic AI

Q: If I use Pydantic AI, what specific data does it touch regarding subscribers?

It accesses subscriber records via listsubscribers. Because of the framework, you'll receive these user identifiers and associated metadata in a guaranteed, validated format.

Guarantee clean Substack data output using the Pydantic AI framework.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect Substack MCP to Pydantic AI

Create your Vinkius account to connect Substack to Pydantic AI — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup Substack with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Validate post performance metrics.

When you call `get_post_stats`, the Pydantic-AI wrapper ensures the returned JSON matches your expected model. If Substack sends bad or corrupted data, the agent fails loudly with a validation error. You never have to worry about silent corruption in your downstream processes; the structure is guaranteed.

Manage and type-check subscribers.

Using `list_subscribers`, you get subscriber data that is strictly typed. This means every single record—like an email or a join date—is validated against your Pydantic schema at runtime. It gives you the certainty that this data will behave exactly as expected when you process it with any model, regardless of its origin.

Process reliable content metadata.

The `get_publication_info` tool provides a validated object containing core Substack details. This is perfect for initial setup checks or building an agent that needs to know the exact type and format of platform data. It forces correctness into your workflow, which is critical when you're running mission-critical automation.

Setup guide

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

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

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

The MCP Server exposes the Substack tools. When your agent calls a tool, Pydantic-AI intercepts the output and validates it against Python models before you ever see it.

It's invaluable. If your workflow requires chaining multiple tool calls, the type-safety prevents errors that usually creep in at the handoff points between specialized agents.

It provides guaranteed structure. Whether you're getting stats from `get_post_stats` or lists of users, the output is always a clean Python object matching your definition.

It supports unified approaches using Streamable HTTP and SSE transports. You just pass the external MCP Server URL, making it model-agnostic regardless of your primary LLM.

It accesses subscriber records via `list_subscribers`. Because of the framework, you'll receive these user identifiers and associated metadata in a guaranteed, validated format.

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