Model Context Protocol Integration with Future AGI Tracing

Connect trace context across MCP client/server transports. MCP instrumentation propagates context; it does not create a complete agent or tool span tree by itself. The Python example uses OpenAI Agents instrumentation to create those spans. The TypeScript example creates an application span around an MCP request.

1. Installation

First install the traceAI package to access the observability framework

pip install "traceAI-mcp>=0.1.3" "mcp>=1.8.1,<2"

npm install @traceai/mcp @traceai/fi-core @opentelemetry/api @opentelemetry/instrumentation '@modelcontextprotocol/sdk@^1.10.2'

pip install traceAI-openai-agents

2. Set Environment Variables

Supply your Future AGI keys through the environment. The Python example also needs an OpenAI key. Python requires 3.11–3.13 for traceAI-mcp.

The OpenAI Agents example can send prompts, file contents read by tools, tool arguments/results and error details to Future AGI. Set FI_HIDE_INPUTS=true and FI_HIDE_OUTPUTS=true before initializing the Python instrumentors to hide input/output values and messages; see mask span attributes. These switches do not sanitize arbitrary custom attributes or all error text. Only expose a dedicated sample directory to the filesystem server, never your home directory or a repository containing secrets. MCP context propagation itself does not redact data sent to a model or an MCP server.

By default, OpenAIAgentsInstrumentor replaces the Agents SDK’s tracing processors with Future AGI’s processor. Passing exclusive_processor=False adds it alongside existing processors instead, so those destinations may also receive trace data.

import os

os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
os.environ["FI_API_KEY"] = "your-futureagi-api-key"
os.environ["FI_SECRET_KEY"] = "your-futureagi-secret-key"

process.env.FI_API_KEY = "your-futureagi-api-key";
process.env.FI_SECRET_KEY = "your-futureagi-secret-key";
// If your MCP client/server uses OpenAI tools, also set:
// process.env.OPENAI_API_KEY = "your-openai-api-key";

3. Initialize Trace Provider

Set up the trace provider to create a new project in FutureAGI, establish telemetry data pipelines.

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="mcp_project",
)

import { register, ProjectType } from "@traceai/fi-core";

const tracerProvider = register({
  projectType: ProjectType.OBSERVE,
  projectName: "mcp_project",
});

4. Instrument your Project

Initialize MCP instrumentation. The Python example also instruments OpenAI Agents; the TypeScript example instruments MCP stdio modules.

from traceai_openai_agents import OpenAIAgentsInstrumentor
from traceai_mcp import MCPInstrumentor

OpenAIAgentsInstrumentor().instrument(tracer_provider=trace_provider)
MCPInstrumentor().instrument(tracer_provider=trace_provider)

import { MCPInstrumentation } from "@traceai/mcp";
import * as MCPClientStdioModule from "@modelcontextprotocol/sdk/client/stdio.js";
import * as MCPServerStdioModule from "@modelcontextprotocol/sdk/server/stdio.js";

// MCP must be manually instrumented as it doesn't have a traditional module structure
const mcpInstrumentation = new MCPInstrumentation({});
mcpInstrumentation.manuallyInstrument({
  clientStdioModule: MCPClientStdioModule,
  serverStdioModule: MCPServerStdioModule,
});

5. Interact with MCP Server

For the Python example, install Node.js 24 or later so npx is available, and create a sample_files directory beside your script with files you want the agent to read. Continue the script after the setup above:

import asyncio
import os
import shutil

from agents import Agent, Runner
from agents.mcp import MCPServer, MCPServerStdio

async def run(mcp_server: MCPServer):
    agent = Agent(
        name="Assistant",
        instructions="Use the tools to read the filesystem and answer questions based on those files.",
        mcp_servers=[mcp_server],
    )

    message = "Read the files and list them."
    print(f"Running: {message}")
    result = await Runner.run(starting_agent=agent, input=message)
    print(result.final_output)

async def main():
    current_dir = os.path.dirname(os.path.abspath(__file__))
    samples_dir = os.path.join(current_dir, "sample_files")

    async with MCPServerStdio(
        name="Filesystem Server, via npx",
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
        },
    ) as server:
        await run(server)

if __name__ == "__main__":
    if not shutil.which("npx"):
        raise RuntimeError("npx is not installed. Please install Node.js and ensure npx is on your PATH.")

    try:
        asyncio.run(main())
    finally:
        trace_provider.shutdown()

TypeScript client request

Use Node.js 24 or later. Save the TypeScript setup above and the request below together as example.mts, then run npx tsx example.mts from that directory. Create an empty sample_files directory beside the script first. This example lists the server’s available tools without asking a model to read files.

import { resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const samplesDir = fileURLToPath(new URL("./sample_files/", import.meta.url));
const client = new Client({ name: "sample-client", version: "1.0.0" });
const transport = new MCPClientStdioModule.StdioClientTransport({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", resolve(samplesDir)],
});

try {
  await client.connect(transport);
  const tracer = tracerProvider.getTracer("mcp-example");
  await tracer.startActiveSpan("list-mcp-tools", async (span) => {
    try {
      const result = await client.listTools();
      console.log(result.tools.map((tool) => tool.name));
    } finally {
      span.end();
    }
  });
} finally {
  try {
    await client.close();
  } finally {
    await tracerProvider.shutdown();
  }
}

The list-mcp-tools span is application instrumentation, not a span automatically created by @traceai/mcp. A server needs its own tracing setup to produce server-side spans. Do not add filenames, arguments or results as custom span attributes unless you intend to export them.

View the trace

Open Observe in Future AGI and select the mcp_project project to inspect the trace.