> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vexlo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an agent

> Run the Vexlo MCP server, connect a client and verify read access.

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](https://docs.vexlo.ai/deployment/install.md) to prepare a server and
[Authentication](https://docs.vexlo.ai/deployment/authentication.md) 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:

```sh theme={"system"}
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:

```sh theme={"system"}
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:

```sh theme={"system"}
claude
```

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

```sh theme={"system"}
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:

```json theme={"system"}
{
  "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](https://docs.vexlo.ai/agents/use-data.md) 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:

```text theme={"system"}
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](https://docs.vexlo.ai/deployment/troubleshooting.md).

## Develop the MCP server

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

```sh theme={"system"}
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:

```sh theme={"system"}
claude mcp remove --scope project vexlo
```

Register the local executable:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.