Connect an agent

Use npx -y @vexlo/mcp to run the Vexlo MCP server. Your MCP client launches it as a stdio process, which reads recorded execution from your Vexlo server over HTTP. This guide uses Claude Code; other MCP clients use the same command, server URL and read credential.

Prerequisites

A Vexlo server with recorded data and a read-role token for the relevant teams.
Node.js 20 or later and npm.
Claude Code installed and authenticated for the walkthrough.

Use Install and run to prepare a server and Authentication to issue a read credential. An ingest token cannot be used by the MCP server.

Configure Claude Code

From your application project, set the server address and read token, replacing the example values:

export VEXLO_API_URL=http://127.0.0.1:8080
export VEXLO_TOKEN=your-read-token

Use the server’s origin, such as http://127.0.0.1:8080, without /v1. Both variables are required in every shell that starts Claude Code; the project configuration resolves them when launching the MCP process. Register Vexlo for this project:

claude mcp add --scope project \
  --env 'VEXLO_API_URL=${VEXLO_API_URL}' 'VEXLO_TOKEN=${VEXLO_TOKEN}' \
  --transport stdio vexlo -- npx -y @vexlo/mcp

Claude Code writes the project entry to .mcp.json. The quoted variable references remain in that file and expand from the environment when the server launches, so the command above does not embed the token’s value in the project configuration. Start Claude Code from the project:

claude

Alternatively, start a session that loads MCP servers only from this file:

claude --mcp-config .mcp.json --strict-mcp-config

The file can contain other server entries; --strict-mcp-config excludes MCP configuration from other sources. Approve a project-scoped server when Claude Code requests trust, then use /mcp to inspect its status. Other clients have their own stdio registration settings; .mcp.json is specific to this Claude Code setup.

Verify the connection

Ask Claude Code to call vexlo_check_coverage with an empty argument object. An example response:

{
  "services": [
    {
      "service": "checkout-investigation",
      "traces_24h": 2,
      "marked_functions_seen": 12,
      "records_lost_24h": 0,
      "records_shed_24h": 0,
      "last_seen_at": "2026-11-09T00:18:02.159Z"
    }
  ]
}

Check that the response contains the service you expect to read. If it is missing, check the read token’s team scope and whether the application has delivered records to this instance. Continue with Use execution data to query calls, values and function usage.

Connection failures

Startup validates configuration, checks /v1/capabilities, then checks the token’s identity through /v1/whoami before registering tools.

Exit	Failed stage
`1`	Missing, empty or invalid required configuration.
`2`	Capabilities request failed or its response was unusable.
`3`	Server reports an API version other than the supported `v1`.
`4`	Token identity request failed.
`5`	Token resolves to a role other than `read`.
`70`	Unexpected MCP process failure.

A startup with empty required variables returned:

invalid startup configuration —
VEXLO_API_URL: Invalid URL
VEXLO_TOKEN: Too small: expected string to have >=1 characters

For a connection that succeeds but cannot find expected data, verify token scope, service identity and application delivery using Troubleshooting.

Develop the MCP server

To modify or test the MCP server, build a local checkout with Git:

git clone https://github.com/vexlo-ai/vexlo-mcp.git
cd vexlo-mcp
npm ci
npm run build
export VEXLO_MCP_ENTRY="$PWD/dist/index.js"

The built entry point is dist/index.js. Return to your application project in the same terminal, keeping VEXLO_MCP_ENTRY, VEXLO_API_URL and VEXLO_TOKEN set. If the project already has a vexlo entry, remove it first:

claude mcp remove --scope project vexlo

claude mcp add --scope project \
  --env 'VEXLO_API_URL=${VEXLO_API_URL}' 'VEXLO_TOKEN=${VEXLO_TOKEN}' \
  --transport stdio vexlo -- node "$VEXLO_MCP_ENTRY"

Getting started

AI agents

Instrumentation

Web UI

Using execution data

Deployment and administration

Examples

Reference

Connect an agent

Prerequisites

Configure Claude Code

Verify the connection

Connection failures

Develop the MCP server

​Prerequisites

​Configure Claude Code

​Verify the connection

​Connection failures

​Develop the MCP server

Prerequisites

Configure Claude Code

Verify the connection

Connection failures

Develop the MCP server