How to integrate Docker hub MCP with Pydantic AI

Trusted by
AWS
Glean
Zoom
Airtable
GET STARTED FOR FREEGET A DEMO

30 min · no commitment · see it on your stack

Docker hub logo
Pydantic AI logo
divider

Introduction

This guide walks you through connecting Docker hub to Pydantic AI using the Composio tool router. By the end, you'll have a working Docker hub agent that can create a new docker hub repository, add a member to your docker organization, delete an old image from a repository through natural language commands.

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

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

Also integrate Docker hub 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 Docker hub
  • 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 Docker hub 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 Docker hub MCP server, and what's possible with it?

The Docker hub MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Docker Hub account. It provides structured and secure access to your container repositories and organizations, so your agent can perform actions like creating repositories, managing organization members, deleting images, setting up webhooks, and cleaning up tags on your behalf.

  • Repository and image management: Let your agent create new Docker Hub repositories, delete existing ones, and remove specific images or tags as needed.
  • Organization and team automation: Easily add members to organizations, create new Docker Hub organizations, or delete organizations and teams directly from your workflows.
  • Webhook configuration: Set up or remove repository webhooks to automate external integrations and keep your CI/CD pipelines in sync.
  • Tag and resource cleanup: Direct your agent to delete outdated tags or unused resources, helping you maintain a tidy container registry.
  • Secure role management: Invite users with specific roles to your organizations, ensuring the right access for collaborators and teams.

Supported Tools & Triggers

Tools
Add Organization MemberInvite a user to join a Docker Hub organization.
Create Docker Hub OrganizationCreate a new Docker Hub organization.
Create Docker Hub RepositoryCreates a new Docker Hub repository under the specified namespace.
Create Docker Hub WebhookCreate a webhook on a Docker Hub repository to receive notifications on image push events.
Delete Repository ImagesDelete one or more images from your Docker Hub namespace using the bulk delete API.
Delete Docker Hub OrganizationPermanently deletes a Docker Hub organization.
Delete Docker Hub RepositoryPermanently deletes a Docker Hub repository and all its images/tags.
Delete Repository TagPermanently delete a specific tag from a Docker Hub repository.
Delete Docker Hub TeamPermanently deletes a team from a Docker Hub organization.
Delete Docker Hub repository webhookDeletes a specific webhook from a Docker Hub repository.
Get Docker Hub ImageRetrieve details about a specific platform-specific image variant by its digest.
Get Docker Hub RepositoryRetrieves detailed information about a specific Docker Hub repository.
Get Docker Hub TagTool to retrieve details of a specific Docker Hub repository tag.
Get Docker Hub TeamRetrieve details of a specific team (group) within a Docker Hub organization.
Get Docker Hub WebhookRetrieves details of a specific Docker Hub webhook by its ID.
List Organization Access TokensTool to list all organization access tokens for a Docker Hub organization.
List Docker Hub OrganizationsList Docker Hub organizations that the authenticated user belongs to.
List Docker Hub Organization MembersLists members of a Docker Hub organization with their roles and details.
List Docker Hub RepositoriesTool to list repositories under a namespace.
List Team MembersList members of a Docker Hub team (group) within an organization.
List Organization TeamsList all teams (groups) within a Docker Hub organization.
List Docker Hub repository webhooksLists all webhooks configured for a Docker Hub repository.
Remove Organization MemberRemove a member from a Docker Hub organization.
Remove Team MemberRemove a user from a Docker Hub organization team (group).

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

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

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.

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 Docker hub
  • pydantic-ai lets you create structured AI agents with tool support
  • python-dotenv loads your environment variables securely from a .env file

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

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 Docker hub
  • MCPServerStreamableHTTP connects to the Docker hub MCP server endpoint
  • Agent from Pydantic AI lets you define and run the AI assistant

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 Docker hub
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["docker_hub"],
    )
    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 Docker hub 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

Initialize the Pydantic AI Agent

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

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 Docker hub.\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
  • Docker hub API calls happen automatically under the hood
  • The model keeps conversation history to maintain context across turns

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 Docker hub 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 Docker hub
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["docker_hub"],
    )
    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
    docker_hub_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
    agent = Agent(
        "openai:gpt-5",
        toolsets=[docker_hub_mcp],
        instructions=(
            "You are a Docker hub assistant. Use Docker hub 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 Docker hub.\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 Docker hub through Composio's Tool Router. With this setup, your agent can perform real Docker hub 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 + Docker hub for workflow automation)
This architecture makes your AI agent "agent-native", able to securely use APIs in a unified, composable way without custom integrations.

How to build Docker hub MCP Agent with another framework

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Docker hub MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Docker hub MCP with Claude Agent SDK

Claude Code logo

Claude Code

Use Docker hub MCP with Claude Code

Claude Cowork logo

Claude Cowork

Use Docker hub MCP with Claude Cowork

Codex logo

Codex

Use Docker hub MCP with Codex

OpenClaw logo

OpenClaw

Use Docker hub MCP with OpenClaw

Hermes logo

Hermes

Use Docker hub MCP with Hermes

CLI logo

CLI

Use Docker hub MCP with CLI

Google ADK logo

Google ADK

Use Docker hub MCP with Google ADK

LangChain logo

LangChain

Use Docker hub MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Docker hub MCP with Vercel AI SDK

Mastra AI logo

Mastra AI

Use Docker hub MCP with Mastra AI

LlamaIndex logo

LlamaIndex

Use Docker hub MCP with LlamaIndex

CrewAI logo

CrewAI

Use Docker hub MCP with CrewAI

FAQ

What are the differences in Tool Router MCP and Docker hub MCP?

With a standalone Docker hub MCP server, the agents and LLMs can only access a fixed set of Docker hub tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Docker hub and many other apps based on the task at hand, all through a single MCP endpoint.

Can I use Tool Router MCP with Pydantic AI?

Yes, you can. Pydantic AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Docker hub tools.

Can I manage the permissions and scopes for Docker hub while using Tool Router?

Yes, absolutely. You can configure which Docker hub scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Docker hub data and credentials are handled as safely as possible.

Used by agents from

Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai

Never worry about agent reliability

We handle tool reliability, observability, and security so you never have to second-guess an agent action.

Get started for freeGet a demo↗