Repository Public
1# Integrations and observability23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45After the workflow shape is clear, the next questions are which external surfaces should live inside the agent loop and how you will inspect what actually happened at runtime.67## Choose what lives in the SDK89| Need | Start with | Why |10| --------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |11| Give an agent access to public, remotely hosted MCP tools | Hosted MCP tools in the SDK | The model can call the remote MCP server through the hosted surface |12| Connect local or private MCP servers from your runtime | SDK-managed MCP servers over stdio or streamable HTTP | Your runtime owns the connection, approvals, and network boundaries |13| Debug prompts, tools, handoffs, or approvals | Built-in tracing | Traces show the end-to-end record before you formalize evals |1415Tool capability semantics still live in [Using tools](https://developers.openai.com/api/docs/guides/tools). This page focuses on the SDK-specific MCP wiring and observability loop.1617## MCP1819Use hosted MCP tools when the remote server should run through the model surface.2021Attach a hosted MCP server2223```javascript24import { Agent, hostedMcpTool } from "@openai/agents";2526const agent = new Agent({27 name: "MCP assistant",28 instructions: "Use the MCP tools to answer questions.",29 tools: [30 hostedMcpTool({31 serverLabel: "gitmcp",32 serverUrl: "https://gitmcp.io/openai/codex",33 }),34 ],35});36```3738```python39from agents import Agent, HostedMCPTool4041agent = Agent(42 name="MCP assistant",43 instructions="Use the MCP tools to answer questions.",44 tools=[45 HostedMCPTool(46 tool_config={47 "type": "mcp",48 "server_label": "gitmcp",49 "server_url": "https://gitmcp.io/openai/codex",50 "require_approval": "never",51 }52 )53 ],54)55```565758Use local transports when your application should connect to the MCP server directly.5960Connect a local MCP server6162```javascript63import { Agent, MCPServerStdio, run } from "@openai/agents";6465const server = new MCPServerStdio({66 name: "Filesystem MCP Server",67 fullCommand:68 "npx -y @modelcontextprotocol/server-filesystem fixtures/sample_files",69});7071await server.connect();7273try {74 const agent = new Agent({75 name: "Filesystem assistant",76 instructions: "Read files with the MCP tools before answering.",77 mcpServers: [server],78 });7980 const result = await run(agent, "Read the files and list them.");81 console.log(result.finalOutput);82} finally {83 await server.close();84}85```8687```python88import asyncio8990from agents import Agent, Runner91from agents.mcp import MCPServerStdio929394async def main() -> None:95 async with MCPServerStdio(96 name="Filesystem MCP Server",97 params={98 "command": "npx",99 "args": [100 "-y",101 "@modelcontextprotocol/server-filesystem",102 "./sample_files",103 ],104 },105 ) as server:106 agent = Agent(107 name="Filesystem assistant",108 instructions="Read files with the MCP tools before answering.",109 mcp_servers=[server],110 )111 result = await Runner.run(agent, "Read the files and list them.")112 print(result.final_output)113114115if __name__ == "__main__":116 asyncio.run(main())117```118119120The practical split is:121122- Use **hosted MCP** for public remote servers that fit the platform trust model.123- Use **local or private MCP** when your runtime should own connectivity, filtering, or approvals.124125For the platform-wide concept, trust model, and product support story, keep [MCP servers](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) as the canonical reference.126127## Tracing128129Tracing is built into the Agents SDK and is enabled by default in the normal server-side SDK path. Every run can emit a structured record of model calls, tool calls, handoffs, guardrails, and custom spans, which you can inspect in the [Traces dashboard](https://platform.openai.com/traces).130131The default trace usually gives you:132133- the overall run or workflow134- each model call135- tool calls and their outputs136- handoffs and guardrails137- any custom spans you wrap around the workflow138139If you need less tracing, use the SDK-level or per-run tracing controls rather than removing all observability from the workflow.140141Wrap multiple runs in one trace142143```javascript144import { Agent, run, withTrace } from "@openai/agents";145146const agent = new Agent({147 name: "Joke generator",148 instructions: "Tell funny jokes.",149});150151await withTrace("Joke workflow", async () => {152 const first = await run(agent, "Tell me a joke");153 const second = await run(agent, `Rate this joke: ${first.finalOutput}`);154 console.log(first.finalOutput);155 console.log(second.finalOutput);156});157```158159```python160import asyncio161162from agents import Agent, Runner, trace163164agent = Agent(165 name="Joke generator",166 instructions="Tell funny jokes.",167)168169170async def main() -> None:171 with trace("Joke workflow"):172 first = await Runner.run(agent, "Tell me a joke")173 second = await Runner.run(174 agent,175 f"Rate this joke: {first.final_output}",176 )177 print(first.final_output)178 print(second.final_output)179180181if __name__ == "__main__":182 asyncio.run(main())183```184185186Use traces for two jobs:187188- Debug one workflow run and understand what happened.189- Feed higher-signal examples into [agent workflow evaluation](https://developers.openai.com/api/docs/guides/agent-evals) once you are ready to score behavior systematically.190191## Next steps192193Once the external surfaces are wired in, continue with the guide that covers capability design, review boundaries, or evaluation.194195196197 [Using tools198199200201 See how hosted tools, function tools, and agents-as-tools fit beside MCP.](https://developers.openai.com/api/docs/guides/tools#usage-in-the-agents-sdk)202 [Guardrails and human review203204205206 Add approval or validation boundaries around sensitive capabilities.](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals)207 [Agent workflow evaluation208209210211 Move from one-off traces into repeatable grading once behavior stabilizes.](https://developers.openai.com/api/docs/guides/agent-evals)