diff --git a/.github/workflows/fastmcp-native.yml b/.github/workflows/fastmcp-native.yml
new file mode 100644
index 000000000..b9c0e6e08
--- /dev/null
+++ b/.github/workflows/fastmcp-native.yml
@@ -0,0 +1,43 @@
+name: FastMCP native examples
+
+on:
+ pull_request:
+ branches: [main]
+ paths:
+ - 'src/pages/docs/integrations/frameworks/fastmcp.mdx'
+ - 'scripts/test_fastmcp_native.py'
+ - 'scripts/fastmcp-page.test.mjs'
+ - 'src/lib/integrations.mjs'
+ - '.github/workflows/fastmcp-native.yml'
+
+permissions:
+ contents: read
+
+jobs:
+ native-contract:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - python: '3.10'
+ fastmcp: '4.1.0'
+ - python: '3.13'
+ fastmcp: '4.1.5'
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python }}
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ - name: Install published packages
+ run: python -m pip install "fastmcp==${{ matrix.fastmcp }}" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http pytest
+ - name: Check native guide discovery and wording
+ run: node --test scripts/fastmcp-page.test.mjs
+ - name: Run real snippets with loopback networking only
+ run: |
+ PYTHON=$(command -v python)
+ sudo unshare --net bash -c 'ip link set lo up; exec "$1" -I -m pytest --noconftest -q "$2"' -- "$PYTHON" "$PWD/scripts/test_fastmcp_native.py"
diff --git a/scripts/fastmcp-page.test.mjs b/scripts/fastmcp-page.test.mjs
new file mode 100644
index 000000000..ef1aa11f0
--- /dev/null
+++ b/scripts/fastmcp-page.test.mjs
@@ -0,0 +1,36 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { integrations } from '../src/lib/integrations.mjs';
+
+const route = '/docs/integrations/frameworks/fastmcp';
+
+test('native MCP and FastMCP routes remain distinct and discoverable', () => {
+ assert.ok(integrations.some(item => item.id === 'mcp-python' && item.href === '/docs/integrations/traceai/mcp-python'));
+ const generic = readFileSync(new URL('../src/pages/docs/integrations/traceai/mcp.mdx', import.meta.url), 'utf8');
+ assert.ok(generic.includes('](/docs/integrations/traceai/mcp-python)'));
+ assert.ok(generic.includes(`](${route})`));
+});
+
+test('native CI covers the declared floor and current published patch', () => {
+ const workflow = readFileSync(new URL('../.github/workflows/fastmcp-native.yml', import.meta.url), 'utf8');
+ assert.match(workflow, /fastmcp: '4\.1\.0'/);
+ assert.match(workflow, /fastmcp: '4\.1\.5'/);
+});
+
+test('Python FastMCP has its own discoverable native setup', () => {
+ assert.ok(integrations.some(item => item.id === 'fastmcp-python' && item.href === route));
+ const page = readFileSync(new URL(`../src/pages${route}.mdx`, import.meta.url), 'utf8');
+ assert.match(page, /fastmcp>=4\.1\.0,<4\.2/);
+ assert.match(page, /trace\.set_tracer_provider\(provider\)/);
+ assert.match(page, /project_name/);
+ assert.match(page, /project_type.*observe/);
+ assert.match(page, /X-Api-Key/);
+ assert.match(page, /X-Secret-Key/);
+ assert.match(page, /provider\.shutdown\(\)/);
+ assert.match(page, /mcp\.session\.id/);
+ assert.match(page, /\*\*Unknown\*\*/);
+ assert.match(page, /exception messages and stack traces/);
+ assert.match(page, /FI_HIDE_INPUTS.*FI_HIDE_OUTPUTS.*FI_HIDE_ERROR_DETAILS/);
+ assert.doesNotMatch(page, /MCPInstrumentor\(\)|class .*Exporter|class .*Processor/);
+});
diff --git a/scripts/test_fastmcp_native.py b/scripts/test_fastmcp_native.py
new file mode 100644
index 000000000..3b3c1ac8b
--- /dev/null
+++ b/scripts/test_fastmcp_native.py
@@ -0,0 +1,229 @@
+"""Execute the page's exact snippets with published FastMCP and a loopback OTLP receiver.
+
+Install fastmcp, opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http and
+pytest first. Run with outbound networking denied except localhost.
+"""
+
+import gzip
+import os
+from pathlib import Path
+import re
+import signal
+import socket
+import subprocess
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest
+import pytest
+
+PAGE = Path(__file__).resolve().parents[1] / "src/pages/docs/integrations/frameworks/fastmcp.mdx"
+# -I prevents ambient Python imports; only our extracted, authored examples are added.
+LOADER = "import sys,runpy; sys.path.insert(0,sys.argv[1]); runpy.run_path(sys.argv[2],run_name='__main__')"
+
+
+def attrs(items):
+ return {item.key: getattr(item.value, item.value.WhichOneof("value")) for item in items}
+
+
+@pytest.fixture
+def example(tmp_path):
+ blocks = re.findall(r"```python\n# (\w+\.py)\n(.*?)\n```", PAGE.read_text(), re.S)
+ assert {name for name, _ in blocks} == {"tracing.py", "server.py", "client.py"}
+ for name, code in blocks:
+ (tmp_path / name).write_text(code)
+ (tmp_path / "home").mkdir()
+ return tmp_path
+
+
+@pytest.fixture
+def receiver():
+ received = []
+
+ class Handler(BaseHTTPRequestHandler):
+ def do_POST(self):
+ data = self.rfile.read(int(self.headers["Content-Length"]))
+ compressed = self.headers.get("Content-Encoding") == "gzip"
+ if compressed:
+ data = gzip.decompress(data)
+ payload = ExportTraceServiceRequest.FromString(data)
+ received.append((self.path, dict(self.headers), compressed, payload))
+ self.send_response(200)
+ self.send_header("Content-Type", "application/x-protobuf")
+ self.send_header("Content-Length", "0")
+ self.end_headers()
+
+ def log_message(self, *_args):
+ pass
+
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ try:
+ yield f"http://127.0.0.1:{server.server_port}/tracer/v1/traces", received
+ finally:
+ server.shutdown()
+ server.server_close()
+ thread.join(timeout=5)
+
+
+def environment(example, receiver, compression):
+ return {
+ "PATH": str(Path(sys.executable).parent) + os.pathsep + os.defpath,
+ "HOME": str(example / "home"),
+ "FI_API_KEY": "synthetic-fastmcp-api",
+ "FI_SECRET_KEY": "synthetic-fastmcp-secret",
+ "FI_PROJECT_NAME": "fastmcp-calculator",
+ "FASTMCP_TELEMETRY_MODE": "native",
+ "FASTMCP_CHECK_FOR_UPDATES": "off",
+ "FI_HIDE_INPUTS": "true",
+ "FI_HIDE_OUTPUTS": "true",
+ "FI_HIDE_ERROR_DETAILS": "true",
+ "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": receiver[0],
+ "OTEL_EXPORTER_OTLP_TRACES_COMPRESSION": compression,
+ "OTEL_BSP_SCHEDULE_DELAY": "60000",
+ }
+
+
+def command(example, name):
+ return [sys.executable, "-I", "-c", LOADER, str(example), str(example / name)]
+
+
+def run(example, name, env):
+ result = subprocess.run(command(example, name), cwd=example, env=env,
+ capture_output=True, text=True, timeout=45)
+ assert result.returncode == 0, result.stderr
+ return result.stdout
+
+
+def exported(receiver, compression):
+ assert receiver[1], "no OTLP export reached the receiver"
+ spans = []
+ for path, headers, compressed, payload in receiver[1]:
+ headers = {key.lower(): value for key, value in headers.items()}
+ assert path == "/tracer/v1/traces"
+ assert headers["content-type"] == "application/x-protobuf"
+ assert headers["x-api-key"] == "synthetic-fastmcp-api"
+ assert headers["x-secret-key"] == "synthetic-fastmcp-secret"
+ assert compressed == (compression == "gzip")
+ for resource in payload.resource_spans:
+ resource_attrs = attrs(resource.resource.attributes)
+ assert resource_attrs["project_name"] == "fastmcp-calculator"
+ assert resource_attrs["project_type"] == "observe"
+ for scope in resource.scope_spans:
+ for span in scope.spans:
+ assert span.end_time_unix_nano >= span.start_time_unix_nano
+ # Export credentials belong only in HTTP headers, never span data.
+ assert b"synthetic-fastmcp" not in span.SerializeToString()
+ spans.append((scope.scope.name, span))
+ assert len({span.span_id for _, span in spans}) == len(spans)
+ return spans
+
+
+def assert_tool_ancestry(spans, tool="add"):
+ native = [span for scope, span in spans
+ if scope == "fastmcp" and attrs(span.attributes).get("gen_ai.tool.name") == tool]
+ server = [span for span in native if span.kind == 2] # OTLP SERVER
+ client = [span for span in native if span.kind == 3] # OTLP CLIENT
+ assert len(server) == len(client) == 1, "one native execution and one logical call"
+ assert server[0].trace_id == client[0].trace_id
+ by_id = {span.span_id: span for _, span in spans}
+ parent = server[0]
+ visited = set()
+ while parent.span_id != client[0].span_id:
+ assert parent.span_id not in visited, "cycle in exported parent chain"
+ visited.add(parent.span_id)
+ parent = by_id[parent.parent_span_id]
+ assert attrs(server[0].attributes)["mcp.method.name"] == "tools/call"
+ return server[0], client[0]
+
+
+@pytest.mark.parametrize("compression", ["none", "gzip"])
+def test_exact_http_snippets(example, receiver, compression):
+ env = environment(example, receiver, compression)
+ with socket.socket() as reserved:
+ reserved.bind(("127.0.0.1", 0))
+ env["MCP_PORT"] = str(reserved.getsockname()[1])
+ process = subprocess.Popen(command(example, "server.py"), cwd=example, env=env,
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ try:
+ deadline = time.monotonic() + 30
+ while True:
+ try:
+ with socket.create_connection(("127.0.0.1", int(env["MCP_PORT"])), timeout=0.2):
+ break
+ except OSError:
+ assert process.poll() is None, process.communicate()[1]
+ assert time.monotonic() < deadline, "server did not become ready"
+ threading.Event().wait(0.05)
+ assert run(example, "client.py", env).strip() == "5"
+ finally:
+ if process.poll() is None:
+ process.send_signal(signal.SIGINT)
+ try:
+ _, stderr = process.communicate(timeout=15)
+ except subprocess.TimeoutExpired:
+ process.kill()
+ process.communicate()
+ pytest.fail("server did not shut down cleanly")
+ assert process.returncode == 0, stderr
+ assert_tool_ancestry(exported(receiver, compression))
+
+
+@pytest.mark.parametrize("transport", ["inprocess", "stdio"])
+@pytest.mark.parametrize("compression", ["none", "gzip"])
+def test_native_transport_and_privacy(example, receiver, transport, compression):
+ env = environment(example, receiver, compression)
+ # Test-only operations expose whether normal content and errors enter telemetry.
+ (example / "operations.py").write_text('''from server import server
+@server.tool
+def echo(value: str) -> str:
+ return value
+@server.tool
+def fail() -> str:
+ raise ValueError("synthetic-error-detail")
+''')
+ (example / "stdio_server.py").write_text('''from tracing import provider
+from operations import server
+try:
+ server.run(transport="stdio", show_banner=False)
+finally:
+ provider.shutdown()
+''')
+ if transport == "inprocess":
+ target = "from operations import server\ntarget = server"
+ else:
+ target = f'''import os, sys
+from fastmcp.client.transports import StdioTransport
+target = StdioTransport(command=sys.executable, args={command(example, "stdio_server.py")[1:]!r}, env=dict(os.environ))'''
+ (example / "probe.py").write_text('''import asyncio
+from tracing import provider
+from fastmcp import Client
+from fastmcp.exceptions import ToolError
+''' + target + '''
+async def main():
+ async with Client(target) as client:
+ assert (await client.call_tool("add", {"a": 2, "b": 3})).data == 5
+ assert (await client.call_tool("echo", {"value": "synthetic-normal-content"})).data == "synthetic-normal-content"
+ try:
+ await client.call_tool("fail", {})
+ except ToolError:
+ pass
+ else:
+ raise AssertionError("tool error was swallowed")
+try:
+ asyncio.run(main())
+finally:
+ provider.shutdown()
+''')
+ run(example, "probe.py", env)
+ spans = exported(receiver, compression)
+ assert_tool_ancestry(spans)
+ assert_tool_ancestry(spans, "echo")
+ errors = assert_tool_ancestry(spans, "fail")
+ assert all(span.status.code == 2 for span in errors)
+ assert not any(b"synthetic-normal-content" in span.SerializeToString() for _, span in spans)
+ # Pin the warning: native errors are NOT sanitized by traceAI hide flags.
+ assert any(b"synthetic-error-detail" in span.SerializeToString() for _, span in spans)
diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs
index a29553b74..ae406302f 100644
--- a/src/lib/integrations.mjs
+++ b/src/lib/integrations.mjs
@@ -82,6 +82,7 @@ export const integrations = [
{ id: 'instructor', name: 'Instructor', href: '/docs/integrations/traceai/instructor', category: 'frameworks', summary: 'Trace structured-output requests and validation.', method: 'traceAI SDK', logo: 'instructor' },
{ id: 'promptflow', name: 'Prompt Flow', href: '/docs/integrations/traceai/promptflow', category: 'frameworks', summary: 'Trace OpenAI calls inside Prompt Flow pipelines.', method: 'OpenAI client', logo: 'promptflow', aliases: ['PromptFlow'] },
{ id: 'guardrails', name: 'Guardrails AI', href: '/docs/integrations/traceai/guardrails', category: 'frameworks', summary: 'Capture validation and guard execution spans.', method: 'traceAI SDK', logo: 'guardrails' },
+ { id: 'fastmcp-python', name: 'FastMCP Python', href: '/docs/integrations/frameworks/fastmcp', category: 'frameworks', summary: 'Export native Python MCP client and server spans.', method: 'Native OTLP', logo: 'mcp' },
{ id: 'mcp-python', name: 'MCP for Python', href: '/docs/integrations/traceai/mcp-python', category: 'frameworks', summary: 'Export native MCP 2.x client requests and server tool spans.', method: 'Native OTLP', logo: 'mcp', aliases: ['Model Context Protocol Python'] },
{ id: 'mcp', name: 'Model Context Protocol', href: '/docs/integrations/traceai/mcp', category: 'frameworks', summary: 'Propagate context with TypeScript and existing Python MCP integrations.', method: 'traceAI SDK', logo: 'mcp', aliases: ['MCP'] },
{ id: 'mastra', name: 'Mastra', href: '/docs/integrations/traceai/mastra', category: 'frameworks', summary: 'Trace TypeScript agents and workflows in Mastra.', method: 'traceAI SDK', logo: 'mastra' },
diff --git a/src/pages/docs/integrations/frameworks/fastmcp.mdx b/src/pages/docs/integrations/frameworks/fastmcp.mdx
new file mode 100644
index 000000000..0cbff028f
--- /dev/null
+++ b/src/pages/docs/integrations/frameworks/fastmcp.mdx
@@ -0,0 +1,159 @@
+---
+title: "FastMCP Python tracing"
+description: "Send native FastMCP client and server spans to Future AGI with OpenTelemetry, without a second instrumentor."
+---
+
+Trace Python FastMCP tool calls across client and server processes in Future AGI. FastMCP creates the spans and propagates their context; a standard OpenTelemetry provider exports them.
+
+This guide uses **FastMCP 4.1.x** and **Python 3.10 or later**. It covers the Python `fastmcp` package, not the unrelated TypeScript package. You do not need `traceAI-mcp`, a model API key, or an additional MCP instrumentation wrapper for this native route. For older or non-native MCP implementations, use the [generic MCP integration](/docs/integrations/traceai/mcp).
+
+## Install
+
+Create and activate a virtual environment, then install:
+
+```bash
+python -m pip install "fastmcp>=4.1.0,<4.2" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
+```
+
+## Configure tracing
+
+Set these variables in **both** the client and server environments. Get your keys from [API keys](/docs/admin-settings/api-keys).
+
+```bash
+export FI_API_KEY="your-api-key"
+export FI_SECRET_KEY="your-secret-key"
+export FI_PROJECT_NAME="fastmcp-calculator"
+export FASTMCP_TELEMETRY_MODE="native"
+```
+
+
+Native spans can contain exception messages and stack traces, tool/prompt names, resource URIs, and authenticated identity metadata. Normal tool arguments and return values are not automatically captured by this setup, but they can appear in an exception. Keep secrets and personal data out of names, URIs and errors, or route through an OpenTelemetry Collector with your redaction policy before exporting. `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS` and `FI_HIDE_ERROR_DETAILS` do not sanitize this standard OpenTelemetry route.
+
+
+Save this standard exporter configuration as `tracing.py`:
+
+```python
+# tracing.py
+import os
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+provider = TracerProvider(
+ resource=Resource.create({
+ "service.name": "fastmcp-calculator",
+ "project_name": os.environ["FI_PROJECT_NAME"],
+ "project_type": "observe",
+ })
+)
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
+ endpoint=os.environ.get(
+ "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+ "https://api.futureagi.com/tracer/v1/traces",
+ ),
+ headers={
+ "X-Api-Key": os.environ["FI_API_KEY"],
+ "X-Secret-Key": os.environ["FI_SECRET_KEY"],
+ },
+)))
+trace.set_tracer_provider(provider)
+```
+
+`project_name` and `project_type` must be **resource attributes**. `service.name` alone does not select a Future AGI project. The exporter sends OTLP/HTTP protobuf to the full traces URL, with both authentication headers; do not point it at a gRPC port or a metrics/logs endpoint.
+
+For self-hosted Future AGI, set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to your deployment's full `/tracer/v1/traces` URL. Leave compression unset for uncompressed export. If your deployment accepts gzip, set `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION=gzip`.
+
+
+Use one global provider per process. If your application already configures OpenTelemetry, add this exporter to that provider instead of creating another one. Initialize it before starting the FastMCP client or server, and shut it down after the application finishes. Do not add a second MCP span-producing wrapper on top of native tracing.
+
+
+## Start a server
+
+Save `server.py` beside `tracing.py`:
+
+```python
+# server.py
+import asyncio
+import os
+
+from tracing import provider
+from fastmcp import FastMCP
+
+server = FastMCP("calculator")
+
+@server.tool
+def add(a: int, b: int) -> int:
+ """Add two integers."""
+ return a + b
+
+if __name__ == "__main__":
+ try:
+ server.run(
+ transport="http",
+ host="127.0.0.1",
+ port=int(os.environ.get("MCP_PORT", "8000")),
+ )
+ except (KeyboardInterrupt, asyncio.CancelledError):
+ pass
+ finally:
+ provider.shutdown()
+```
+
+```bash
+python server.py
+```
+
+The example binds only to loopback. Add [FastMCP authentication](https://gofastmcp.com/servers/auth/authentication) before exposing a server beyond your machine. Future AGI exporter credentials authenticate telemetry export, not MCP requests.
+
+## Call the tool
+
+Save `client.py` in the same directory. In a second terminal, activate the same virtual environment and set the same tracing variables, then run:
+
+```python
+# client.py
+import asyncio
+import os
+
+from tracing import provider
+from fastmcp import Client
+
+async def main():
+ port = int(os.environ.get("MCP_PORT", "8000"))
+ async with Client(f"http://127.0.0.1:{port}/mcp") as client:
+ result = await client.call_tool("add", {"a": 2, "b": 3})
+ print(result.data)
+
+if __name__ == "__main__":
+ try:
+ asyncio.run(main())
+ finally:
+ provider.shutdown()
+```
+
+```bash
+python client.py
+```
+
+The client prints `5`. Stop the server with Ctrl+C when finished so its provider drains pending spans too.
+
+### Stdio or in-process clients
+
+The same provider configuration works with FastMCP's [stdio transport](https://gofastmcp.com/clients/transports) and `Client(server)` in-process clients. A stdio server is a separate process: configure its provider and pass its tracing environment explicitly. Keep stdout reserved for the MCP protocol. An in-process client and server share **one** provider; do not initialize it twice.
+
+## View the trace
+
+Open **Observe**, select **fastmcp-calculator**, and find the `tools/call add` spans. The client operation and server execution belong to the same trace. The MCP SDK can also create intermediate transport spans; those are not additional tool executions.
+
+Inspect native attributes such as `mcp.method.name`, `gen_ai.tool.name` and `fastmcp.server.name`. Native MCP spans do not set a Future AGI span-kind label, so they can appear with an **Unknown** type; inspect their names and attributes to identify tool executions. These are operation spans, not model usage spans: FastMCP does not infer token counts, model costs or tool input/output panels. Instrument model clients separately when you need model telemetry.
+
+`mcp.session.id` identifies an MCP transport session where available; it is **not** a Future AGI conversation grouping key. If your application needs conversation grouping, set `session.id` or `gen_ai.conversation.id` on the application spans that represent that conversation. Do not rename an MCP transport ID into an end-user conversation ID.
+
+## Troubleshooting
+
+- **No native spans:** check that the SDK is installed, the provider is registered before requests, and `FASTMCP_TELEMETRY_MODE` is `native`. `propagation_only` forwards context without creating FastMCP spans; `off` disables FastMCP's own spans and context handling. MCP SDK or HTTP instrumentation can still emit its own spans.
+- **Only one side of the call appears:** configure the provider and exporter in both processes, using the same project name. A client exporter cannot export a remote server's spans.
+- **Export fails or the project is missing:** check the full traces endpoint, both key headers and the resource attributes. Give the process time to shut down cleanly; a forced kill cannot drain a batch queue.
+- **Duplicate operation spans:** remove overlapping MCP instrumentation. If another tracing stack owns your MCP operation spans, use FastMCP's `propagation_only` mode instead of its native mode.
diff --git a/src/pages/docs/integrations/traceai/mcp.mdx b/src/pages/docs/integrations/traceai/mcp.mdx
index b92010568..70685255d 100644
--- a/src/pages/docs/integrations/traceai/mcp.mdx
+++ b/src/pages/docs/integrations/traceai/mcp.mdx
@@ -7,6 +7,8 @@ Connect trace context across MCP client/server transports. MCP instrumentation p
For new Python integrations, use [native MCP 2.x tracing](/docs/integrations/traceai/mcp-python). It creates client and server tool spans without an agent framework or model API key. Do not add `MCPInstrumentor` to that native setup. The Python example below is the existing MCP 1.x propagation route; the TypeScript instructions are separate.
+
+Using Python FastMCP 4.1.x? Follow the [native FastMCP guide](/docs/integrations/frameworks/fastmcp) instead. FastMCP already creates and propagates its own spans; it does not need this additional MCP instrumentor.
## 1. Installation