TraceNexus

⚠️ WORK IN PROGRESS ⚠️

This project is currently under active development and should be considered experimental. Features may change, and stability is not guaranteed.

Please DM the author if you have any comments, suggestions, or would like to contribute!

A platform-agnostic MCP (Model Context Protocol) server for LLM observability, supporting platforms like LangSmith and Langfuse. It runs both transport protocols simultaneously: streamable-http (for Cursor) and SSE (for Windsurf) using FastMCP 2.0.

Features

• 🔄 Support for multiple tracing platforms through a unified interface
• 🛠️ MCP tools for retrieving and analyzing traces
• 📊 Trace comparison across different platforms
• 🚀 Dual transport support: Runs both streamable-http and SSE simultaneously
• 📡 Cursor compatibility: streamable-http transport on port 52734
• 🌊 Windsurf compatibility: SSE transport on port 52735
• 🤖 Claude Code compatibility: Full MCP integration support
• 🧩 Easy integration with LangSmith and LangFuse
• 🔧 Use multiple clients at the same time with one server

Quick Start (for End Users)

This guide provides the quickest way to get the TraceNexus server up and running.

1. Prerequisites

• Python 3.9+ (developed with 3.11)

2. Installation

1. (Optional but Recommended) Create a dedicated directory and set up a virtual environment:

   mkdir ~/my_tracenexus_server
   cd ~/my_tracenexus_server
   python -m venv .venv
   source .venv/bin/activate

2. Install TraceNexus from PyPI:

   pip install --upgrade tracenexus

3. Configuration (API Keys & Settings)

TraceNexus requires API keys for the tracing platforms it supports (e.g., LangSmith, Langfuse).

• Create a .env file in your project directory (e.g., ~/my_tracenexus_server/.env if you followed the optional step above, or in the directory where you run tracenexus).
• Add your API keys and desired default platform to this file. The server automatically loads these settings on startup.

Example .env file:

# LangSmith Configuration - Multiple Instances Support
# Comma-separated API keys for different LangSmith workspaces/projects
LANGSMITH_API_KEYS="prod-api-key,dev-api-key,test-api-key"
# Names for each instance (will be used in tool names)
LANGSMITH_NAMES="prod,dev,test"
# This creates tools: langsmith_prod_get_trace, langsmith_dev_get_trace, langsmith_test_get_trace

# Langfuse Configuration - Multiple Instances Support
# Comma-separated configuration for different Langfuse projects/environments
LANGFUSE_PUBLIC_KEYS="pub-key-1,pub-key-2,pub-key-3"
LANGFUSE_SECRET_KEYS="secret-key-1,secret-key-2,secret-key-3"
LANGFUSE_HOSTS="https://cloud.langfuse.com,https://cloud.langfuse.com,https://self-hosted.example.com"
# Names for each instance (will be used in tool names)
LANGFUSE_NAMES="prod,dev,test"
# This creates tools: langfuse_prod_get_trace, langfuse_dev_get_trace, langfuse_test_get_trace

Note:

• For LangSmith: The number of names should match the number of API keys
• For Langfuse: The number of public keys, secret keys, hosts, and names should all match
• If names are not provided or don't match, auto-generated names (instance1, instance2, etc.) will be used

Refer to tracenexus/cli.py (if installed from source) or use tracenexus --help for details on how provider-specific API keys are checked at startup.

4. Running the Server

Once installed and configured, run the server using:

tracenexus

This will start both transport protocols simultaneously:

• 📡 Streamable-HTTP (Cursor): http://localhost:52734/mcp
• 🌊 SSE (Windsurf): http://localhost:52735/sse

To see all available command-line options, including changing ports:

tracenexus --help

Custom ports example:

tracenexus --http-port 8000 --sse-port 8001

5. Using with MCP Client Applications

TraceNexus runs both transport protocols simultaneously, so you can use Claude Code, Cursor, and Windsurf at the same time!

For Claude Code

1. Follow steps 1-3 from the Quick Start section above to install TraceNexus and set up your .env file with API keys.

2. Start the TraceNexus server:

   tracenexus

3. Add TraceNexus to Claude Code using the CLI:

   # Recommended: Use streamable-http transport for better stability
   claude mcp add tracenexus --transport streamable-http --url http://localhost:52734/mcp
   
   # Alternative: SSE transport (may have initialization issues)
   # claude mcp add tracenexus --transport sse --url http://localhost:52735/sse

That's it! Claude Code can now use the trace retrieval tools. Tool names follow the pattern langsmith_<instance_name>_get_trace and langfuse_<instance_name>_get_trace where instance names come from your configuration (with dashes converted to underscores).

To verify it's working, you can ask Claude: "What MCP tools do you have available?"

For Cursor (Streamable-HTTP)

1. Ensure the TraceNexus server is running (e.g., via tracenexus).
2. In Cursor's MCP server settings, add:

{
  "mcpServers": {
    "tracenexus": {
      "transport": "streamable-http",
      "url": "http://localhost:52734/mcp" 
    }
  }
}

For Windsurf (SSE)

1. Ensure the TraceNexus server is running (e.g., via tracenexus).
2. In Windsurf's MCP server settings, add:

{
  "mcpServers": {
    "tracenexus": {
      "serverUrl": "http://localhost:52735/sse"
    }
  }
}

Note: Both configurations can be used simultaneously with the same server instance!

Available Tools

Once running, the server exposes the following MCP tools:

LangSmith Tools (Multiple Instances)

• langsmith_<name>_get_trace: Retrieve a single trace by ID from a specific LangSmith instance
  • Example: langsmith_prod_get_trace, langsmith_dev_get_trace, langsmith_test_get_trace
  • The actual tool names depend on your LANGSMITH_NAMES configuration

Langfuse Tools (Multiple Instances)

• langfuse_<name>_get_trace: Retrieve a single trace by ID from a specific Langfuse instance
  • Example: langfuse_prod_get_trace, langfuse_dev_get_trace, langfuse_test_get_trace
  • The actual tool names depend on your LANGFUSE_NAMES configuration

An example Python client showing how to connect and use these tools can be found in examples/client.py.

Development Setup

If you want to contribute to TraceNexus, modify the source code, or run it directly from a cloned repository, follow these steps.

1. Prerequisites

• Python 3.9+ (developed with 3.11)
• Poetry (for dependency management)

2. Installation & Setup (from Source)

# Clone the repository
git clone https://github.com/sharrajesh/tracenexus.git
cd tracenexus

# Install dependencies (including development dependencies)
make install-dev
# or poetry install --with dev

3. Configuration

Follow the same .env file configuration steps outlined in "Quick Start (for End Users) -> 3. Configuration". Place the .env file in the root of the cloned tracenexus directory.

4. Running the Server (from Source)

# Run the TraceNexus server (runs both transports: HTTP on 52734, SSE on 52735)
make run

This uses poetry run tracenexus. You can also run poetry run tracenexus --help for options.

Development

• Formatting, Linting & Type Checking: make format (uses isort and black to reformat code, ruff to check and auto-fix linting issues, and mypy for type checking).
• Tests: make test

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.