How to Use the Unsplash MCP in OpenAI Agents SDK

Q: How do I search for photos from Unsplash using the OpenAI Agents SDK?

You simply call searchphotos and provide your keywords. The tool returns IDs, URLs, and photographer info right away.

Q: What is the best way to find new inspiration with Unsplash and the OpenAI Agents SDK?

The easiest method is using getrandomphoto. It pulls a random high-res image for you, which is great when your creative team needs quick visual mockups.

Q: Can I find collections of photos from Unsplash with the OpenAI Agents SDK?

Yes. Use searchcollections to search by keyword (like 'Food' or 'Travel'). Then, if you get a collection ID, you can call listcollectionphotos to see everything inside.

Q: Does the OpenAI Agents SDK handle attribution when searching Unsplash photos?

Yes. When you use searchphotos, the results include proper attribution details for every photo returned, which is critical for your final output.

Find high-res creative assets and build image search pipelines using the OpenAI Agents SDK.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Unsplash MCP to OpenAI Agents SDK

Create your Vinkius account to connect Unsplash to OpenAI Agents SDK 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 Unsplash with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Search for specific photos across Unsplash.

The `search_photos` tool lets your agent find images, returning IDs, URLs, and necessary attribution details. You don't have to guess what keywords work; just input the criteria and get a list of relevant results. Need one inspiration shot? Use `get_random_photo`. It grabs a random high-resolution photo, giving you quick visual filler for your creative assets without running another search.

Discover curated content categories on Unsplash.

Start by using `list_editorial_topics` to see what types of content are trending—like 'Nature' or 'Architecture.' This helps scope the initial request, keeping your agent focused. If you know a general theme but not an exact topic, try `search_collections`. You can search for curated groups of photos using keywords like 'Industrial' or 'Minimalist'.

Track and retrieve content from specific creators.

Find photographers by name or username with `search_photographers` to build a roster of talent. Once you have their profile, the agent can call `get_photographer_photos` to pull all recent work uploaded by that user. Want more details on one specific shot? Call `get_photo_details` using its ID. This gives you everything you need about a single Unsplash photo.

Setup guide

Set up Unsplash MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Unsplash tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Unsplash tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Unsplash tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Unsplash Agent",
            instructions="You have access to Unsplash tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

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 Unsplash. 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 Unsplash 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 Unsplash MCP in OpenAI Agents SDK

You simply call `search_photos` and provide your keywords. The tool returns IDs, URLs, and photographer info right away.

The easiest method is using `get_random_photo`. It pulls a random high-res image for you, which is great when your creative team needs quick visual mockups.

Yes. Use `search_collections` to search by keyword (like 'Food' or 'Travel'). Then, if you get a collection ID, you can call `list_collection_photos` to see everything inside.

Yes. When you use `search_photos`, the results include proper attribution details for every photo returned, which is critical for your final output.

You'll be dealing with Photo IDs and URLs. The agent uses these identifiers to pull specific details or list contents.

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