from openai import OpenAI
client = OpenAI()
r = client.responses.create(
model="gpt-5",
tools=[{
"type": "mcp",
"server_label": "poseidon",
"server_url": "https://api.askposeidon.app/mcp",
"headers": {"Authorization": "Bearer psd_..."},
"require_approval": "never",
}],
input="What are the winning UGC formats for weight loss in France? Go look in Poseidon.",
)
print(r.output_text)
ChatGPT connectors are coming.
Tools
Tool
What it does
Cost
filters
Free. What Poseidon can filter on, with live counts: niches, Meta display formats, countries with reach data, age ranges, hook types (none measured yet), sort orders, the winner rule and the coverage note. Call it first.
Free
search_winners
Find winning e-commerce ads from the Meta Ad Library (EU/UK delivered ads, confirmed e-commerce shops only). Winner = live 21+ days by default. Each result: the ad's link on the Ad Library, the brand and its shop link, format, days live, versions (Meta's count of ads sharing the creative), active or stopped, EU reach (Meta's total, the only number of people) with the day it was read, the share of Meta's age x gender breakdown in the country / segment you filtered on (a share, never people), and the verbatim hook when its script was cut into sections. A field we don't have is absent, never guessed. No media and no person-name search. Costs 5 credits per search (0 if nothing matches). Arguments: niche, country, format, hook_type, age, gender, active, min_days_live, max_days_live, min_eu_reach, min_country_share, min_segment_share, min_versions, has_script, started_after, started_before, sort, limit, offset
5 credits
search_experiments
Brands' own A/B tests: ads of one brand launched within 14 days that share one element and differ in another (same video with different ad texts, same text with different videos, same script with a different hook). Each variant: its ads with Ad Library links, launch day, active or stopped, days live and EU reach (Meta's total) with read date, plus the text that differs. The outcome is measured (a variant still running while another stopped, or 2x+ the reach), and absent when nothing is clear yet. Costs 5 credits (0 if nothing matches). Arguments: niche, country, kind, with_outcome, limit, offset
5 credits
get_ad
One ad in full: Ad Library link, brand and shop, ad copy, format, dates, versions, EU reach history (Meta's total per read day; countries and age x gender as shares of Meta's breakdown), the verbatim script sentence by sentence with each sentence's section (Hook, Problem, Proof, Offer, CTA…, and who labelled it), change history and the source of every field. Costs 2 credits. Arguments: ad_id
2 credits
get_brand
A brand: its Ad Library page link, shop (link, platform), how it was found, its ads in Poseidon (counts by format, winners, median days live, ads with reach) and its 10 longest-running ads. Give page_id or the shop domain. Costs 5 credits. Arguments: page_id, domain
5 credits
get_weights
Weights of formats, hook types and targets from measured signals only (days live, EU reach, reach growth, versions), each with its sample size, median and top 10%. Weights under the minimum sample are never shown. Until the weighting engine runs this returns nothing. 10 credits per query (0 if nothing is returned). Arguments: dimension, value, signal, niche, country, limit
10 credits
account
Free. Your credits left (they never expire), prices, last calls and credit movements.
