Skip to content

Connect: OpenAI Agents SDK for TypeScript

Recipe · through our MCP server · their docs checked 2026-11-16 · tested live

@openai/agents runs the agent loop in your Node process. MCPServerStreamableHttp connects it to our /mcp endpoint; the agent calls our tools like its own. For the Python Agents SDK, use the in-process integration instead.

Our side

def public_app(tools: Registry, host: str, agent_token: str, reviewer_token: str) -> Any:
    """REST at /, MCP at /mcp, one bearer check for both: for a host on the internet."""
    from mcp.server.transport_security import TransportSecuritySettings

    from agent_adapter.server import create_app

    tokens = {
        agent_token: Principal("hosted-agent"),  # the token the remote framework sends
        reviewer_token: Principal("reviewer@example.com", scopes=frozenset({APPROVER_SCOPE})),
    }
    security = TransportSecuritySettings(allowed_hosts=[host], allowed_origins=[f"https://{host}"])
    return create_app(
        tools,
        authenticate=bearer_auth(tokens),
        host="0.0.0.0",  # a public bind: the public-host checks apply
        allowed_hosts=[host],  # REST: any other Host header gets 421
        mcp_options={"transport_security": security},  # MCP: the same rule
    )


hosted = registry.subset(tags=["hosted"])  # no confirm tools: hosted runtimes cannot resume them

Serve public_app(hosted, …), or filter confirm tools out on their side: the SDK does not send our resume keys back. In development on one machine, local_app() is enough.

Their side

npm i @openai/agents:

import { Agent, MCPServerStreamableHttp, run } from "@openai/agents";

const shopTools = new MCPServerStreamableHttp({
  url: "https://tools.example.com/mcp",
  name: "shop_tools",
  requestInit: { headers: { Authorization: `Bearer ${process.env.AA_AGENT_TOKEN}` } },
  cacheToolsList: true,
});

await shopTools.connect();
try {
  const agent = new Agent({
    name: "Shop assistant",
    instructions: "Answer shipping questions with the tools.",
    mcpServers: [shopTools],
  });
  const result = await run(agent, "What is the shipping rate to the US?");
  console.log(result.finalOutput);
} finally {
  await shopTools.close();
}
Key Meaning
url our /mcp endpoint (Streamable HTTP)
requestInit.headers carries the bearer token on every request
cacheToolsList lists our tools once per connection; leave it off while you change the registry
toolFilter createMCPToolStaticFilter({ allowed: [...] }) keeps tools out of the model's view
mcpServers on Agent the agent sees every tool the server lists

examples/connect/js/check.ts runs this client, Vercel AI SDK, Mastra and Genkit against our live server: each lists the tools, calls shipping_rate, and sees send_invoice park with approval required: apr_… instead of running.

Approvals

The SDK's human-in-the-loop (needsApproval, result.interruptions, result.state.approve(...)) pauses its own run. It adds a gate; it never approves our confirm tools. For a side effect, call our REST route from a function tool and let your reviewer decide with POST /approvals/{id}/decide (the TS client wraps both).

hostedMcpTool({ serverLabel, serverUrl, requireApproval }) is the other way in: OpenAI's servers call ours, as on the OpenAI hosted MCP page.

Checklist

Check Why
serve hosted, or toolFilter the confirm tools out the SDK does not send our resume keys back; a confirm tool parks on every call
close() in finally the client keeps a session open on our server
the token stays on the server process.env, never in a browser bundle
everything on the public-host checklist

Sources