OpenAI Agents SDK

Plug STACK into the OpenAI Agents SDK as a streamable HTTP MCP server. The agent process holds a passport; STACK holds the credentials and injects them server-side. Whatever the agent reaches — Slack, GitHub, Stripe, an internal API — runs through one chain you control.

For the broader why-this-matters framing — what STACK adds on top of the SDK, when it's the right call, what it unlocks for self-hosted backends and cross-runtime fleets — read /with/openai-agents-sdk. This page is the technical guide.

1. Install

bash
pip install openai-agents

TypeScript users can use @openai/agents with the equivalent MCPServerStreamableHttp primitive.

2. Get a STACK API key

Sign up at getstack.run (free tier, no credit card). Copy the API key from the dashboard, then export it in your shell:

bash
export STACK_API_KEY="sk_live_..."

3. Wire STACK in as an MCP server

python
import os
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

stack_token = os.environ["STACK_API_KEY"]

async def main() -> None:
    async with MCPServerStreamableHttp(
        name="STACK",
        params={
            "url": "https://mcp.getstack.run/mcp",
            "headers": {"Authorization": f"Bearer {stack_token}"},
            "timeout": 30,
        },
    ) as stack:
        agent = Agent(
            name="Assistant",
            instructions=(
                "You are a helpful assistant. Use STACK to access "
                "user-authorized services securely. Never store or "
                "echo raw credentials."
            ),
            mcp_servers=[stack],
        )

        result = await Runner.run(agent, "Send a message in #alerts: deploy completed.")
        print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

The agent can now call any STACK tool — stack_register_agent, stack_issue_passport, stack_proxy_request, stack_invoke_skill, stack_create_dropoff — and proxy outbound calls to any of the connected services in your STACK operator account.

4. Bearer vs OAuth

For backend code, the simplest path is the API key as a Bearer token (the example above). The API key represents an operator (you) and lets your code mint passports for the agents it runs.

If you need per-end-user OAuth on top — for example, an SDK-driven app where each customer logs in and authorises STACK individually — STACK's OAuth 2.1 + DCR endpoint at https://api.getstack.run/.well-known/oauth-authorization-server works the same way as it does for the Workspace Agents path. You implement the standard authorisation-code flow with PKCE and pass the resulting access token in the headers dict instead of the API key.

5. Tools available

  • stack_register_agent — register a new agent under your operator.
  • stack_issue_passport — mint a short-lived passport for a specific intent.
  • stack_proxy_request — make an authenticated call through the credential-injecting proxy.
  • stack_invoke_skill — run a published skill in a sealed sandbox.
  • stack_list_services — see which upstream services are connected.
  • stack_create_dropoff / stack_collect — schema-validated agent-to-agent hand-off.
  • stack_get_passport_report — read the audit trail for a passport.
  • stack_revoke_passport — sub-60s revocation, cascades to delegated children.

Full tool reference at /docs/mcp-tools.

Next

  • Concepts: passports — what passports are and how scope narrows down a delegation chain.
  • Concepts: detectors — the runtime detectors that fire at the proxy boundary.
  • API: proxy — the per-call request shape if you bypass MCP and call the proxy directly.
  • API: audit — exporting the hash-chained audit log to your SIEM.
stack | docs