Introduction

Model Context Protocol (MCP) Observability is a monitoring solution that provides deep visibility into your MCP server and client interactions. It enables you to monitor the performance of applications that use the Model Context Protocol, a standard way that allows AI assistants such as Claude Desktop and GitHub Copilot to securely connect to external data sources and tools.

What is MCP-Instana Observability?

MCP-Instana Observability integrates with the Traceloop SDK to provide distributed tracing for your MCP server and client interactions. When you enable it, MCP Observability automatically generates spans for key operations. These spans help you:

• Track workflows across server and client components

• Monitor task performance and spot bottlenecks

• Visualize end-to-end request flows

• Analyze patterns to improve performance and stability

In short, it gives you the clear visibility into how your MCP applications work.

You can apply the same Traceloop configuration (either the version mentioned here or the latest traceloop-sdk release) to instrument any other MCP server to provide the same level of visibility.

Here is an architecture of how Instana integrate with traceloop SDK and enable MCP observability.

Prerequisites

Before you enable the observability, make sure that you have the following prerequisites:

• MCP-Instana server (MCP Instana Open Source Project)

• The MCP-Instana open source project provides a reference MCP server that wraps Instana’s APIs behind the Model Context Protocol, making Instana Observability primitives accessible to any MCP-compatible client.

• Install the Traceloop SDK (pip install traceloop-sdk==0.47.5)

• Access to an Instana instance to view spans

• Basic knowledge of distributed tracing

Step-by-Step Configuration

1. Install the Traceloop SDK 0.47.5

Install the required SDK in your MCP server environment:

# using pip
pip install traceloop-sdk==0.47.5

# using uv
uv add traceloop-sdk==0.47.5

If you do not install the SDK, the system displays warnings such as:

Traceloop requested but not installed. Install with: pip install traceloop-sdk

2. Enable the Observability feature

MCP-Instana Observability is a feature-flag controlled. It will be enabled only if the environment variable ENABLE_MCP_OBSERVABILITY is set to a truthy value.

The server reads this flag during startup. If the variable is missing or evaluates to false, the Traceloop instrumentation and exporters are never initialized, even if other observability settings are present.

Make sure that every process that launches the MCP-Instana server whether directly or through a client such as Claude Desktop or Copilot, sets:

ENABLE_MCP_OBSERVABILITY=true

Restart the process after updating this value to make sure that it is applied. For more information, see MCP Instana observability. 

Accepted values:

• Enables observability: true, 1, yes, on

• Disables observability (default): false, 0, no, off

Important: If this flag is set to false value, MCP observability remains completely disabled.

3. Configure Trace Export

The trace export configuration depends on the MCP transport mode used by the client.

Client-specific configurations

Depending on your client (GitHub Copilot, Claude Desktop, or custom MCP client), configuration differs for HTTP mode and STDIO mode.
In all cases, ensure the flag ENABLE_MCP_OBSERVABILITY=true value is set.

GitHub Copilot

HTTP mode (mcp.json)

{
  "servers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: <your-instana-url>",
        "--header", "instana-api-token: <your-instana-token>"
      ],
      "env": {
        "ENABLE_MCP_OBSERVABILITY": "true",
        "TRACELOOP_BASE_URL": "<your-instana-url>",
        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
        "OTEL_EXPORTER_OTLP_INSECURE": "false"
      }
    }
  }
}

STDIO mode ( mcp.json)

{
  "servers": {
    "my-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "src/core/server.py"
      ],
      "cwd": "<path-to-mcp-instana>",
      "env": {
        "INSTANA_BASE_URL": "<your-instana-url>",
        "INSTANA_API_TOKEN": "<your-instana-token>",
        "ENABLE_MCP_OBSERVABILITY": "true",
        "TRACELOOP_BASE_URL": "<your-instana-url>",
        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
        "OTEL_EXPORTER_OTLP_INSECURE": "false"
      }
    }
  }
}

Claude Desktop

HTTP mode (claude_desktop_config.json)

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://0.0.0.0:8080/mcp/",
        "--allow-http",
        "--header", "instana-base-url: <your-instana-url>",
        "--header", "instana-api-token: <your-instana-token>"
      ],
      "env": {
        "ENABLE_MCP_OBSERVABILITY": "true",
        "TRACELOOP_BASE_URL": "<your-instana-url>",
        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
        "OTEL_EXPORTER_OTLP_INSECURE": "false"
      }
    }
  }
}

STDIO mode (claude_desktop_config.json)

{
  "mcpServers": {
    "Instana MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path-to-mcp-instana>",
        "run",
        "src/core/server.py"
      ],
      "cwd": "<path-to-mcp-instana>",
      "env": {
        "INSTANA_BASE_URL": "<your-instana-url>",
        "INSTANA_API_TOKEN": "<your-instana-token>",
        "ENABLE_MCP_OBSERVABILITY": "true",
        "TRACELOOP_BASE_URL": "<your-instana-url>",
        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
        "OTEL_EXPORTER_OTLP_INSECURE": "false"
      }
    }
  }
}

Custom MCP client

• HTTP mode: Same setup as Copilot HTTP (JSON config with headers + observability env vars).

• STDIO Mode: Same setup as Claude STDIO (JSON config with server command, env vars, and observability flag).

Streamable HTTP mode

In case the environment variables do not take effect export these variables in mcp-instana/server terminal. This issue can occur in HTTP mode.

export ENABLE_MCP_OBSERVABILITY=true
export TRACELOOP_BASE_URL=<your-instana-url> 
export TRACELOOP_HEADERS="x-instana-key=*****"
export OTEL_EXPORTER_OTLP_INSECURE=false

For example:

TRACELOOP_BASE_URL= https://otlp-pink-saas.instana.rocks:4317

Start the server explicitly with streamable HTTP transport:

uv run src/core/server.py --transport streamable-http

Then restart the client such as, Copilot, Claude, or custom MCP client, by using its configuration file.

STDIO mode

In STDIO mode, you do not need to start the MCP server manually. The client (GitHub Copilot, Claude Desktop, or custom MCP client) launches the MCP server process based on its configuration file.

Start the client, and it automatically starts the server in the background.

Export modes

You can export traces to Instana in two different modes:

Agent mode :

Export traces to a local Instana agent that runs on your machine:

export TRACELOOP_BASE_URL=<instana-agent-host>:4317
export TRACELOOP_HEADERS="x-instana-key=<agent-key>"
export OTEL_EXPORTER_OTLP_INSECURE=true

Agentless mode (direct to backend):

Export traces directly to the Instana backend:

export TRACELOOP_BASE_URL=<instana-otlp-endpoint>:4317
export TRACELOOP_HEADERS="x-instana-key=<agent-key>"
export OTEL_EXPORTER_OTLP_INSECURE=false

Replace the values with your actual Instana configuration:

• For agent mode, ensure your local Instana agent is running and accessible.

• For agentless mode, use your Instana backend OTLP endpoint and API key.

• Note: Some clients do not show the root span automatically until you close the session. This is a known issue with Traceloop.

• Claude Desktop: Quit the Claude Desktop app after you get the response.

• GitHub Copilot → Stop copilot after getting response.

• If the session remains open, the root span does not appear in the traces.

Viewing Spans in Instana

1. Log in to Instana.

2. Go to Analytics and enable Show internal calls (lower left).

3. Add a filter: Service Name > Instana-MCP-Server (the app name you used with traceloop.init()).

4. Identify Instana-MCP-Server in the service list to view all spans and trace data from your MCP server.

5. Explore the traces, filter by time range, and drill into specific spans.

This view makes it easy to trace requests end-to-end.

See the following example traces from Instana:

You can see complete details with tool name in the preceeding example, get_infrastructure_catalog_plugins.tool. Also, Tool response we will get with mcp.response.value span.

Key benefits

Enabling Observability brings you the following advantages:

• End-to-end visibility: See client-to-server flows

• Performance optimization: Identify bottlenecks with real data

• Error tracking: Pinpoint failure points quickly

• System understanding: Learn how components interact

Troubleshooting

No Spans Visible?

• Make sure that ENABLE_MCP_OBSERVABILITY=true is set

• Verify Traceloop SDK is installed

• Confirm Instana setup

• Make sure that the trace export environment-variables are set correctly.

Missing some spans?

• Confirm that both the server and client have observability that is enabled.

• Make sure that the relevant MCP operations you expect to trace are running.

• Check your application logs for errors or warnings.

Conclusion

Enabling observability in MCP-Instana provides clear insight into system performance, request flows, and error detection across your MCP server and client interactions. Whether you use streamable HTTP mode, STDIO mode, or through tools like Claude Desktop, or GitHub Copilot, Instana provides a unified and consistent view of your system activity.

Observability supports more than troubleshooting, it strengthens operational excellence. After enabling the observability flag in your environment, configure your client, gives you immediate visibility into spans and workflows.

With these configurations in place, you are gain the information needed to optimize, scale, and maintain a reliable MCP-Instana deployment.