Install and configure

Build vexlo-mcp from a checkout, point a client at it, and verify the handshake against a running server.

The Vexlo MCP server is a stdio process your AI agent’s host launches as a child. It holds one API token, calls one Vexlo server’s /v1 read API, and exposes eleven tools. It stores nothing of its own, so installing it means building it and telling the host where it is.

The eleven tools sit on three rungs, and an agent pays for what it opens: find names what exists and never returns a captured value, shape returns one trace’s or one function’s full structure, and values returns the captured bytes of the slots you ask for. Every tool wraps one read route, so the process cannot change anything on the server, mint a token, or reach storage directly.

​

Requirements

• Node.js 20 or later. package.json declares "node": ">=20"; the build below ran on 26.12.0.
• A running Vexlo server, reachable from the machine the host launches the child on.
• A read-role API token for that server.

The token travels in an Authorization header on every call, so a server outside loopback has to be reached over TLS: install and run the server covers that rule and the flag that waives it.

​

Build from a checkout

@vexlo/mcp is not published to the npm registry yet, so there is no npx form and no npm install @vexlo/mcp:

$ npm view @vexlo/mcp
npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/@vexlo%2fmcp - Not found
npm error 404
npm error 404  The requested resource '@vexlo/mcp@*' could not be found or you do not have permission to access it.
npm error 404
npm error 404 Note that you can also install from a
npm error 404 tarball, folder, http url, or git url.
... 1 line omitted
exit status: 1

Build it from a checkout of vexlo-mcp instead. npm ci installs dependencies and writes no dist/; npm run build compiles src/ to dist/ and prepends the shebang that lets the host execute dist/index.js directly:

$ node --version
v26.12.0

$ npm ci

added 232 packages, and audited 233 packages in 6s
... 18 lines omitted
$ ls dist
ls: dist: No such file or directory

$ npm run build

> @vexlo/mcp@0.1.0 build
> rm -rf dist && tsc -p tsconfig.build.json && ./scripts/verify-dist.sh && ./scripts/prepend-shebang.sh dist/index.js


$ ls dist
api-client.js
check-coverage-and-health.js
config.js
environment-filter.js
errors.js
find-related-traces.js
get-function-examples.js
get-function.js
get-trace.js
get-values.js
handle.js
index.js
list-functions-and-tags.js
session-context.js
tool-result.js
trace-search.js

dist/index.js is the file the host runs, and npm run build is the only build step. The build is tsc, not a bundler: dist/index.js imports @modelcontextprotocol/sdk and zod by name, so it resolves both from the node_modules/ that npm ci wrote beside it. Keep the checkout as it is. Copying dist/ somewhere on its own leaves the process dead before it reaches the handshake, and no exit code in the next page’s table applies:

$ cp -R <checkout>/dist ./dist
$ VEXLO_API_URL=http://127.0.0.1:18300 VEXLO_TOKEN=$READ_TOKEN node dist/index.js
node:internal/modules/package_json_reader:343
  throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
        ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@modelcontextprotocol/sdk' imported from <scratch>/isolated/dist/index.js
    at Object.getPackageJSONURL (node:internal/modules/package_json_reader:343:9)
    at packageResolve (node:internal/modules/esm/resolve:751:25)
    at moduleResolve (node:internal/modules/esm/resolve:840:18)
... 11 lines omitted
exit status: 1

​

Mint a read token

Every tool calls a read-role route, so the process refuses to start with any other role. On the machine that holds the server storage directory:

vexlo token create -role read -team <team-id>

The token prints once and is stored hashed. A read token can span several teams (-team a,b), and that set is the token’s team-set. The tools narrow within it, never past it: a tool asked only for teams outside the team-set sends no request at all and answers with an empty result that carries a scope_note naming what it dropped. An empty result is therefore not by itself proof that the request ran, which find reads in full. Mint the token for every team the agent should see, since the process reads both variables once and never widens its own team-set afterwards. Authentication and tokens covers minting, roles, and revocation.

​

Configure your client

Point the host at the built file by absolute path, and pass both environment variables:

{
  "mcpServers": {
    "vexlo": {
      "command": "node",
      "args": ["/absolute/path/to/vexlo-mcp/dist/index.js"],
      "env": {
        "VEXLO_API_URL": "http://localhost:8080",
        "VEXLO_TOKEN": "vxlo_..."
      }
    }
  }
}

Both variables are required and neither has a default:

Variable	Value
VEXLO_API_URL	The server’s bare origin, with its scheme: http://localhost:8080. Never a URL that includes /v1, which every route appends itself.
VEXLO_TOKEN	A read-role API token for that server.

Both are read once, at startup, by one module. Changing either means restarting the process.

​

Verify

Send one initialize request on stdin. The process runs its startup handshake against the server first, so a reply proves the URL, the token, and the server version all check out:

$ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
    | node dist/index.js
{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"vexlo-mcp","version":"0.1.0"}},"jsonrpc":"2.0","id":1}
exit status: 0

The process exits 0 when stdin closes. A non-zero exit means the handshake failed, and the reason is one line on stderr: startup checks and exit codes has the six codes and what each one means. A host that reports the server as failed with no detail is hiding that line, so read the exit code first and the host’s own child-process log second.

tools/list on the same session returns all eleven tools with their argument schemas. Some of the numbers in them are read from the server’s own /v1/capabilities during startup, and some are fixed in this client:

Bound	Where it comes from
vexlo_get_values path, 8 here	the server’s values_max_paths, used directly
vexlo_search_traces limit ceiling	min(100, search_limit_max), so a server reporting less is respected and one reporting more is not followed
vexlo_list_functions and vexlo_list_tags limit ceiling	min(200, search_limit_max), the same rule at this surface’s own higher ceiling
the step page vexlo_get_trace asks the server for	the server’s trace_steps_limit_max
vexlo_search_traces limit default, 10	fixed in this client, below the API’s own default of 50
vexlo_find_related_traces windowHours, 168	fixed in this client
vexlo_check_trace_status traceIds, 100	fixed in this client, from the route’s own cap
vexlo_get_function_examples limit, 5	fixed in this client

A fixed number does not move when the server reports a larger one. The seeded server behind every example on these pages reports search_limit_max: 500, and vexlo_search_traces still refuses limit: 101. The three tool pages give each tool’s bounds as the schemas carry them.