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.

3b. Pre-execution approval gate

Enforced-mode agents can route Intents through STACK's approval queue before executing. The agent calls stack_submit_intent, polls stack_get_intent_approval until the status is terminal, then threads the approval id on stack_proxy_request. Rejection auto-revokes the passport.

Bind the flow in the agent's system prompt. Name the intents that require approval, instruct it to submit and poll before firing, and require it to thread approval_id on every subsequent proxy call. The gate checks the call shape against the approved Intent (service, method, URL host, body); mismatch returns 403 with metadata.gate_reason="call_mismatch".

python
agent = Agent(
    name="Assistant",
    instructions=(
        "You manage Stripe refunds and Slack incident channels.\n"
        "Before any stripe:refunds:create or slack:channels:archive call:\n"
        "  1. stack_submit_intent with the candidate IntentClaim.\n"
        "  2. Poll stack_get_intent_approval until status != 'pending'.\n"
        "  3. If approved, call stack_proxy_request with approval_id.\n"
        "  4. If rejected or expired, stop. Do not retry."
    ),
    mcp_servers=[stack],
)

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_simulate_intent — dry-run an Intent for pre-execution checks (allowed + denial reasons).
  • stack_submit_intent — submit an Intent for operator approval. Required for enforced-mode producer calls.
  • stack_get_intent_approval — poll for the terminal approval decision.
  • 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