Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trulayer.ai/llms.txt

Use this file to discover all available pages before exploring further.

The TruLayer MCP server exposes your observability data as tools that any MCP-compatible host can call — Claude Desktop, Cursor, Windsurf, VS Code Copilot, or your own AI agent. Instead of copy-pasting trace IDs from the dashboard, agents can query traces, fetch eval results, and search spans in context.

​
Prerequisites

  • Node.js 18+ or Python 3.11+
  • A TruLayer API key (tl_...) — get one from Dashboard → Settings → API keys
  • An MCP-compatible host (Claude Desktop, Cursor, Windsurf, VS Code with GitHub Copilot, or a custom agent)

​
Install

The TruLayer MCP server is published to npm. Install it globally or let your MCP host fetch it on demand: 
npm install -g @trulayer/mcp
Or run it directly without installing: 
npx @trulayer/mcp

​
Configure your host

​
Claude Desktop

Add an entry to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows): 
{
  "mcpServers": {
    "trulayer": {
      "command": "npx",
      "args": ["@trulayer/mcp"],
      "env": {
        "TRULAYER_API_KEY": "tl_your_key_here"
      }
    }
  }
}
Restart Claude Desktop. You will see a TruLayer tools indicator in the chat input bar.

​
Claude Code

Install TruLayer as a Claude Code skill so you can query your traces and evals directly from the Claude Code CLI: 
npx @trulayer/mcp install --client claude-code
Or add it manually to your project’s .claude/settings.json: 
{
  "mcpServers": {
    "trulayer": {
      "command": "npx",
      "args": ["-y", "@trulayer/mcp"],
      "env": {
        "TRULAYER_API_KEY": "tl_your_api_key_here"
      }
    }
  }
}
Once installed, use /mcp trulayer in Claude Code to query your workspace.

​
Cursor

Open Settings → MCP and add: 
{
  "trulayer": {
    "command": "npx",
    "args": ["@trulayer/mcp"],
    "env": {
      "TRULAYER_API_KEY": "tl_your_key_here"
    }
  }
}

​
VS Code (GitHub Copilot)

Add to your workspace or user settings.json: 
{
  "mcp": {
    "servers": {
      "trulayer": {
        "command": "npx",
        "args": ["@trulayer/mcp"],
        "env": {
          "TRULAYER_API_KEY": "tl_your_key_here"
        }
      }
    }
  }
}
Set TRULAYER_API_KEY in your environment and run the server as a subprocess: 
export TRULAYER_API_KEY=tl_your_key_here
npx @trulayer/mcp

​
Available tools (skills)

Once connected, the following tools are available to your MCP host:
ToolDescription
list_tracesList recent traces for a project, with optional time bounds and pagination.
get_traceFetch all spans for a single trace by ID.
search_spansSemantic search over spans — find spans by meaning, not just exact text.
list_evalsList eval runs for a project, filtered by scorer and time range.
get_evalFetch a single eval run with per-span scores.
list_metricsPull aggregated latency, token, and cost metrics for a project.
list_feedbackFetch user feedback events attached to traces.
get_projectResolve a project name to its UUID — useful as a first step in a multi-tool workflow.

​
Example interaction

Once the server is running, you can ask your AI host natural-language questions about your traces:
“Show me the 10 most recent traces for the customer-support project and summarize which ones have failing evals.”
The host calls get_project to resolve the name, then list_traces, then list_evals for each trace ID — all without you writing a single API call.

​
Scoping with API key permissions

The MCP server authenticates as the API key you provide. Use a key scoped to read if you only need query access — no write permissions are required for any MCP tool. See API key scopes for how to create a read-only key.

​
Semantic search from an agent

The search_spans tool wraps the same endpoint as Semantic search. When your agent calls it with a natural-language query, TruLayer embeds the text server-side and returns the most similar spans. This requires a BYOK embedding key configured in Dashboard → Settings → Evaluators.

​
Adding TruLayer to a custom MCP host

If you are building your own MCP host or agent framework, connect to the server over stdio: 
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["@trulayer/mcp"],
  env: { TRULAYER_API_KEY: process.env.TRULAYER_API_KEY },
});

const client = new Client({ name: "my-agent", version: "1.0.0" }, {});
await client.connect(transport);

const result = await client.callTool({
  name: "list_traces",
  arguments: { project_id: "<your-project-uuid>", limit: 20 },
});

​
Troubleshooting

The server starts but returns no tools Check that TRULAYER_API_KEY is set and valid. Run npx @trulayer/mcp --version to confirm the package loaded. search_spans returns a 502 A BYOK embedding key is required for text-based search. Configure one in Dashboard → Settings → Evaluators. The host does not show TruLayer tools Some hosts require a restart after adding an MCP server. Check the host’s MCP logs for connection errors.

​
See also