How to integrate Shotstack MCP with Pydantic AI

Connect Pydantic AI to Shotstack MCP. Create a video slideshow from uploaded images, generate a branded video intro with logo, and more using natural language, with authentication handled for you.

Shotstack logoShotstack
Api Key

Shotstack is a cloud platform for programmatically generating videos, images, and audio. Automate creative content production at scale with flexible RESTful APIs.

23 Tools

Introduction

This guide walks you through connecting Shotstack to Pydantic AI using the Composio tool router. By the end, you'll have a working Shotstack agent that can render videos, check render status, create and update templates, upload and inspect media, and fetch generated assets through natural language commands.

This guide will help you understand how to give your Pydantic AI agent real control over a Shotstack account through Composio's Shotstack MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

For exact tool slugs and parameter tables, see the tool catalog in the Composio docs.

Also integrate Shotstack with

TL;DR

Here's what you'll learn:
  • How to set up your Composio API key and User ID
  • How to create a Composio Tool Router session for Shotstack
  • How to attach an MCP Server to a Pydantic AI agent
  • How to stream responses and maintain chat history
  • How to build a simple REPL-style chat interface to test your Shotstack workflows

What is Pydantic AI?

Pydantic AI is a Python framework for building AI agents with strong typing and validation. It leverages Pydantic's data validation capabilities to create robust, type-safe AI applications.

Key features include:

  • Type Safety: Built on Pydantic for automatic data validation
  • MCP Support: Native support for Model Context Protocol servers
  • Streaming: Built-in support for streaming responses
  • Async First: Designed for async/await patterns

What is the Shotstack MCP server, and what's possible with it?

The Shotstack MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Shotstack account. It provides structured and secure access to powerful video, image, and audio automation features—so your agent can create dynamic media content, edit assets, manage rendering jobs, and retrieve results at scale on your behalf.

  • Automated video and image generation: Let your agent assemble and render videos or images programmatically using templates, custom assets, and dynamic data.
  • Media editing and composition: Enable your agent to cut, trim, overlay, and combine media clips—adding text, transitions, or audio tracks as needed.
  • Batch rendering and job management: Have your agent submit, track, and manage multiple rendering jobs, so you can scale creative automation for campaigns or client deliverables.
  • Asset and template organization: Allow your agent to upload, list, and organize reusable templates and media assets, keeping your creative workflow streamlined.
  • Result retrieval and download: Automatically fetch completed renders and download media files, making finished content instantly available for distribution or review.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Python 3.9 or higher
  • A Composio account with an active API key
  • Basic familiarity with Python and async programming
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Navigate to your API settings and generate a new API key.
  • Store this key securely as you'll need it for authentication.
3

Install dependencies

bash
pip install composio pydantic-ai python-dotenv

Install the required libraries.

What's happening:

  • composio connects your agent to external SaaS tools like Shotstack
  • pydantic-ai lets you create structured AI agents with tool support
  • python-dotenv loads your environment variables securely from a .env file
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your agent to Composio's API
  • USER_ID associates your session with your account for secure tool access
  • OPENAI_API_KEY to access OpenAI LLMs
5

Import dependencies

python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()
What's happening:
  • We load environment variables and import required modules
  • Composio manages connections to Shotstack
  • MCPServerStreamableHTTP connects to the Shotstack MCP server endpoint
  • Agent from Pydantic AI lets you define and run the AI assistant
6

Create a Tool Router Session

python
async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Shotstack
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["shotstack"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")
What's happening:
  • We're creating a Tool Router session that gives your agent access to Shotstack tools
  • The create method takes the user ID and specifies which toolkits should be available
  • The returned session.mcp.url is the MCP server URL that your agent will use
7

Initialize the Pydantic AI Agent

python
# Attach the MCP server to a Pydantic AI Agent
shotstack_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
agent = Agent(
    "openai:gpt-5",
    toolsets=[shotstack_mcp],
    instructions=(
        "You are a Shotstack assistant. Use Shotstack tools to help users "
        "with their requests. Ask clarifying questions when needed."
    ),
)
What's happening:
  • The MCP client connects to the Shotstack endpoint
  • The agent uses GPT-5 to interpret user commands and perform Shotstack operations
  • The instructions field defines the agent's role and behavior
8

Build the chat interface

python
# Simple REPL with message history
history = []
print("Chat started! Type 'exit' or 'quit' to end.\n")
print("Try asking the agent to help you with Shotstack.\n")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in {"exit", "quit", "bye"}:
        print("\nGoodbye!")
        break
    if not user_input:
        continue

    print("\nAgent is thinking...\n", flush=True)

    async with agent.run_stream(user_input, message_history=history) as stream_result:
        collected_text = ""
        async for chunk in stream_result.stream_output():
            text_piece = None
            if isinstance(chunk, str):
                text_piece = chunk
            elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                text_piece = chunk.delta
            elif hasattr(chunk, "text"):
                text_piece = chunk.text
            if text_piece:
                collected_text += text_piece
        result = stream_result

    print(f"Agent: {collected_text}\n")
    history = result.all_messages()
What's happening:
  • The agent reads input from the terminal and streams its response
  • Shotstack API calls happen automatically under the hood
  • The model keeps conversation history to maintain context across turns
9

Run the application

python
if __name__ == "__main__":
    asyncio.run(main())
What's happening:
  • The asyncio loop launches the agent and keeps it running until you exit

Complete Code

Here's the complete code to get you started with Shotstack and Pydantic AI:

python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()

async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Shotstack
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["shotstack"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")

    # Attach the MCP server to a Pydantic AI Agent
    shotstack_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
    agent = Agent(
        "openai:gpt-5",
        toolsets=[shotstack_mcp],
        instructions=(
            "You are a Shotstack assistant. Use Shotstack tools to help users "
            "with their requests. Ask clarifying questions when needed."
        ),
    )

    # Simple REPL with message history
    history = []
    print("Chat started! Type 'exit' or 'quit' to end.\n")
    print("Try asking the agent to help you with Shotstack.\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in {"exit", "quit", "bye"}:
            print("\nGoodbye!")
            break
        if not user_input:
            continue

        print("\nAgent is thinking...\n", flush=True)

        async with agent.run_stream(user_input, message_history=history) as stream_result:
            collected_text = ""
            async for chunk in stream_result.stream_output():
                text_piece = None
                if isinstance(chunk, str):
                    text_piece = chunk
                elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                    text_piece = chunk.delta
                elif hasattr(chunk, "text"):
                    text_piece = chunk.text
                if text_piece:
                    collected_text += text_piece
            result = stream_result

        print(f"Agent: {collected_text}\n")
        history = result.all_messages()

if __name__ == "__main__":
    asyncio.run(main())

Conclusion

You've built a Pydantic AI agent that can interact with Shotstack through Composio's Tool Router. With this setup, your agent can perform real Shotstack actions through natural language. You can extend this further by:
  • Adding other toolkits like Gmail, HubSpot, or Salesforce
  • Building a web-based chat interface around this agent
  • Using multiple MCP endpoints to enable cross-app workflows (for example, Gmail + Shotstack for workflow automation)
This architecture makes your AI agent "agent-native", able to securely use APIs in a unified, composable way without custom integrations.
TOOLS

Supported Tools

Every Shotstack action and event your agent gets out of the box.

Create Template

Create a named Shotstack template from timeline and output settings for reuse in media editing and rendering.

Create Template (v2)

Tool to save an Edit as a re-usable template.

Delete Ingested Media

Delete an ingested source file from the production Ingest API by its ingest ID.

Delete Template

Delete a Shotstack template by ID in the stage environment.

Delete Shotstack Workflow

Tool to delete a specific Shotstack workflow.

Fetch Source

Queue a remote media file for ingestion as a source asset in the production Ingest API.

Get Asset

Retrieve details of a hosted asset by asset ID in the Shotstack staging environment, including videos, images, audio files, thumbnails, and poster images.

Get Assets by Render ID

Retrieve hosted assets by render ID in the Shotstack staging environment, including files such as video, thumbnail, and poster images.

Get Render Callback

Request callback details for a specific render job, including the callback URL and delivery status, attempts, response and last-attempt time.

Get Render Status

Retrieve the status and details of a Shotstack render job by render ID in the selected environment.

Get Source Details

Retrieve details and status of a source asset by ID from the production Ingest API.

Get Template

Retrieve a template's details and metadata by ID from the Shotstack staging environment.

Get Template By Version

Tool to retrieve a template by template id and API version.

Get Upload URL

Tool to request a signed URL for direct file upload to Shotstack.

Inspect Media

Tool to inspect media metadata.

List Sources

Request a list of ingested source assets from the production Ingest API, with optional pagination parameters.

List Sources (with Environment)

Tool to list all ingested source files with environment selection.

List Templates

List Shotstack templates for the account in the stage environment.

List Templates with Environment

Tool to list all Shotstack templates for the specified environment.

Request Upload URL

Request a signed URL for direct file upload to the Shotstack staging environment.

Render Video

Tool to initiate a new video render job.

Transfer Asset

Transfer a file from a publicly available URL to one or more production Serve API destinations, including Shotstack hosting or other configured destinations.

Update Template

Update a stage-environment template by ID, providing both its name and complete edit configuration.

FAQ

Frequently asked questions

Start with Shotstack.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Shotstack tool your agent needs.Free to start.

Start building