How to do it
- Create an agent key In https://app.socialhandoff.com, open Connections and add an agent for this app. Grant draft on the networks it will write for.
- Install the SDK Run pip install openai-agents and set OPENAI_API_KEY for the model, plus SOCIAL_AGENT_KEY for SocialHandoff.
- Open the MCP server Create MCPServerStreamableHttp with the /mcp URL and the Authorization header, inside an async with block.
- Attach it to an Agent Pass the server in mcp_servers when you build the Agent. The SDK lists tools and forwards calls.
- Run and review Call Runner.run with your prompt, then approve the resulting drafts in the SocialHandoff inbox.
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
async def main():
async with MCPServerStreamableHttp(
name="social",
params={
"url": "https://app.socialhandoff.com/mcp",
"headers": {"Authorization": "Bearer " + os.environ["SOCIAL_AGENT_KEY"]},
},
cache_tools_list=True,
) as server:
agent = Agent(
name="Launch writer",
instructions="Read brand memory first. Draft posts only; never schedule.",
mcp_servers=[server],
)
result = await Runner.run(agent, "Draft an X thread and a LinkedIn post about today's release.")
print(result.final_output)
asyncio.run(main())How the SDK talks to SocialHandoff
MCPServerStreamableHttp opens a streamable HTTP connection to /mcp, lists the tools, and turns each into a function tool the model can call. cache_tools_list=True avoids re-listing tools on every run, which is safe because the SocialHandoff tool list does not change during a session. The server is stateless and returns JSON, so each call is one request with your bearer key.
Filtering and approvals in the SDK
The SDK supports a tool_filter on MCP servers. Use it to allow only the tools the agent needs, for example get_brand_memory, draft_post, and preview_posts. The SDK's own tool approval features can ask a person before a call runs. That is separate from the SocialHandoff inbox: the SDK approval guards the call, the inbox guards the post.
Useful agent designs
- Release writer: reads a changelog passed as input and drafts one post per network.
- Triage agent with handoffs: a first agent decides whether an event deserves a post, then hands off to a writer agent that has the SocialHandoff tools.
- Weekly planner: calls
plan_weekfor a set of topics and returns the calendar card data for your own UI. - Report bot: with analytics permission, calls
get_insightsand writes a summary for your team. Best-time suggestions are heuristics.
Tracing
The SDK traces runs, including MCP tool calls. Pair that with the SocialHandoff audit log, which records each draft and approval in a hash-chained log you can verify with GET /v1/audit/verify. Together they show which run produced which draft and who approved it.
Troubleshooting
- 401: the header is missing or the key was revoked.
- Timeouts on plan_week: pass a larger
timeoutinparams. - Model ignores the tools: say which tool to use in the instructions, or set
tool_choicein the model settings. - 422 in a tool result: a guardrail rejected the draft; the agent can read the reason and revise.
Per-network examples: OpenAI Agents SDK for X, OpenAI Agents SDK for LinkedIn, OpenAI Agents SDK for Bluesky, OpenAI Agents SDK for Mastodon, and OpenAI Agents SDK for Threads.