MCP server and skills

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"
        }
      }
    }
  }
}

Environment variable (recommended for CI / agent runtimes)

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:

Tool	Description
`list_traces`	List recent traces for a project, with optional time bounds and pagination.
`get_trace`	Fetch all spans for a single trace by ID.
`search_spans`	Semantic search over spans — find spans by meaning, not just exact text.
`list_evals`	List eval runs for a project, filtered by scorer and time range.
`get_eval`	Fetch a single eval run with per-span scores.
`list_metrics`	Pull aggregated latency, token, and cost metrics for a project.
`list_feedback`	Fetch user feedback events attached to traces.
`get_project`	Resolve 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.

Getting started

Core concepts

Python SDK

TypeScript SDK

Go SDK

SDK features

Dashboard

Integrations

Control loop

Guides

Best practices

Reference

Contributing

MCP server and skills

Prerequisites

Install

Configure your host

Claude Desktop

Claude Code

Cursor

VS Code (GitHub Copilot)

Environment variable (recommended for CI / agent runtimes)

Available tools (skills)

Example interaction

Scoping with API key permissions

Semantic search from an agent

Adding TruLayer to a custom MCP host

Troubleshooting

See also

​Prerequisites

​Install

​Configure your host

​Claude Desktop

​Claude Code

​Cursor

​VS Code (GitHub Copilot)

​Environment variable (recommended for CI / agent runtimes)

​Available tools (skills)

​Example interaction

​Scoping with API key permissions

​Semantic search from an agent

​Adding TruLayer to a custom MCP host

​Troubleshooting

​See also

Prerequisites

Install

Configure your host

Claude Desktop

Claude Code

Cursor

VS Code (GitHub Copilot)

Environment variable (recommended for CI / agent runtimes)

Available tools (skills)

Example interaction

Scoping with API key permissions

Semantic search from an agent

Adding TruLayer to a custom MCP host

Troubleshooting

See also