> ## 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. # 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](https://docs.vexlo.ai/mcp/tools/find.md) names what exists and never returns a captured value, [shape](https://docs.vexlo.ai/mcp/tools/shape.md) returns one trace's or one function's full structure, and [values](https://docs.vexlo.ai/mcp/tools/values.md) 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](https://docs.vexlo.ai/server/install.md) 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](https://docs.vexlo.ai/mcp/startup-and-exit-codes.md)'s table applies: ``` $ cp -R /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 /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: ```bash theme={null} vexlo token create -role read -team ``` 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](https://docs.vexlo.ai/mcp/tools/find.md) 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](https://docs.vexlo.ai/server/authentication.md) covers minting, roles, and revocation. ## Configure your client Point the host at the built file by absolute path, and pass both environment variables: ```json theme={null} { "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](https://docs.vexlo.ai/mcp/startup-and-exit-codes.md) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.