Connect MCP tools
Expose your tools to EvoX through an MCP server. This guide implements a read-only integration: an agent reads npm scripts from a fixed project while you verify discovery, invocation, and errors. Connection management and credentials belong in MCP servers. To expose Evolver experience tools to other agents, see Evolver Proxy and MCP.
Define tool scope
Run this local example only in a project directory and parent directories controlled by the runtime account. Other users must not replace these directories or modify the file during a call. The server rejects symbolic links, checks the opened file identity, and reads at most 64 KiB plus one overflow byte from that descriptor; it does not isolate a hostile shared filesystem or provide an OS sandbox.
The example read_project_scripts reads scripts from the startup project's package.json. It does not execute scripts, write files, or access the network. The server's startup argument selects the project; the agent cannot supply arbitrary file paths.
| Contract | This example |
|---|---|
| Input | Empty object {}; additional fields rejected |
| Output | JSON text containing scripts |
| Resource | A regular package.json in a fixed project, limited to 64 KiB |
| Errors | Protocol errors for invalid arguments; isError: true for file failures |
| Side effects | No file writes or command execution |
Create a stdio server
Save the following as read-project-scripts.mjs outside the source project. It uses Node.js built-ins and writes only MCP messages to stdout. A deployed service also needs session management, resource limits, and access controls appropriate to its environment.
import { createInterface } from "node:readline";
import { realpathSync, lstatSync, openSync, fstatSync, readSync, closeSync, constants } from "node:fs";
import { join } from "node:path";
const root = realpathSync(process.argv[2]);
const file = join(root, "package.json");
const tool = {
name: "read_project_scripts",
description: "Read npm scripts from the configured project without executing them.",
inputSchema: { type: "object", properties: {}, additionalProperties: false }
};
const send = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
const fail = (id, code, message) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
const protocolVersion = "2024-11-05";
let phase = "new";
const input = createInterface({ input: process.stdin });
input.on("line", (line) => {
let request;
try { request = JSON.parse(line); }
catch { fail(null, -32700, "Invalid JSON"); return; }
if (!request || typeof request !== "object" || Array.isArray(request)) {
fail(null, -32600, "Invalid request"); return;
}
const { id, method } = request;
if (id !== undefined && typeof id !== "string" && !(typeof id === "number" && Number.isFinite(id))) {
fail(null, -32600, "Invalid request ID"); return;
}
if (request.jsonrpc !== "2.0" || typeof method !== "string") {
fail(id ?? null, -32600, "Invalid request"); return;
}
if (request.params !== undefined && (!request.params || typeof request.params !== "object" || Array.isArray(request.params))) {
if (id !== undefined) fail(id, -32602, "Invalid params");
return;
}
const params = request.params ?? {};
if (id === undefined) {
if (method === "notifications/initialized" && phase === "negotiated") phase = "ready";
return;
}
if (method === "initialize") {
const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
if (phase !== "new" || typeof params.protocolVersion !== "string" || !params.protocolVersion ||
!object(params.capabilities) || !object(params.clientInfo) ||
typeof params.clientInfo.name !== "string" || !params.clientInfo.name ||
typeof params.clientInfo.version !== "string" || !params.clientInfo.version) {
fail(id, -32602, "Invalid or repeated initialization"); return;
}
phase = "negotiated";
send(id, { protocolVersion, capabilities: { tools: {} }, serverInfo: { name: "project-scripts", version: "1.0.0" } });
} else if (method === "ping") {
send(id, {});
} else if (phase !== "ready") {
fail(id, -32002, "Complete initialization before using tools");
} else if (method === "tools/list") {
send(id, { tools: [tool] });
} else if (method === "tools/call") {
const args = params.arguments === undefined ? {} : params.arguments;
if (params.name !== tool.name || !args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).length) {
fail(id, -32602, "Unknown tool or invalid arguments"); return;
}
try {
if (realpathSync(file) !== file) throw new Error("Linked file rejected");
const before = lstatSync(file, { bigint: true });
if (!before.isFile() || before.ino === 0n || before.size > 65536n) throw new Error("File rejected");
const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
let text;
try {
const opened = fstatSync(fd, { bigint: true });
if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) throw new Error("File changed");
const buffer = Buffer.alloc(65537);
let size = 0, count;
while (size < buffer.length && (count = readSync(fd, buffer, size, buffer.length - size, null)) > 0) size += count;
if (size > 65536) throw new Error("File too large");
text = buffer.toString("utf8", 0, size);
} finally { closeSync(fd); }
const pkg = JSON.parse(text);
const scripts = pkg.scripts ?? {};
if (!scripts || typeof scripts !== "object" || Array.isArray(scripts) || Object.values(scripts).some(v => typeof v !== "string")) throw new Error("Invalid scripts");
send(id, { content: [{ type: "text", text: JSON.stringify({ scripts }) }] });
} catch {
send(id, { isError: true, content: [{ type: "text", text: "Cannot read a regular package.json with valid scripts within 64 KiB." }] });
}
} else {
fail(id, -32601, "Method not found");
}
});
This minimal server validates one read-only tool. It handles newline-delimited JSON-RPC messages, without HTTP endpoints, batch requests, or full production service governance. It provides no operating-system sandbox: the process retains its startup user's permissions.
Add and verify in EvoX
Add a manual MCP connection under extensions, select stdio, and supply:
| Field | Example |
|---|---|
| Name | project-scripts |
| Command | Absolute path to the Node.js executable |
| Arguments | Absolute server-script path and absolute project path, as two separate arguments |
Save, then inspect connection and tool discovery. Send the agent:
Use project-scripts/read_project_scripts to read this project's npm scripts.
List script names and commands without executing any scripts.
Compare the result with the project's package.json. Confirm configuration save, process startup, discovery, and invocation separately. A listed server name does not establish a usable tool.
Check protocol and errors
This is a tool-call message. The MCP client must first complete initialize and notifications/initialized. The initialize request supplies protocolVersion, a capabilities object, and clientInfo with name and version strings. This server supports protocol 2024-11-05 and returns that version during negotiation; a client that does not support it must disconnect. Tool calls before the completed handshake are rejected, and ping remains available before initialization.
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_project_scripts","arguments":{}}}
| Case | Required result |
|---|---|
| Regular project | Scripts match the file; none execute |
Extra path argument | Invalid-argument error; no other file is read |
| Missing package.json | Read error rather than a fabricated empty project |
| Oversize or symlink file | Read rejected |
| Server exits | Connection failure; discovery and invocation rechecked after recovery |
Extend with write tools
Give writes separate names and schemas. Define resource identity, edits, preview, consent, and idempotency. Enforce scope and account permissions on the server rather than relying on model compliance. Reconcile real operation state after timeouts to prevent duplicate writes.
On upgrades, compare names, schemas, errors, and side effects, then rerun integration cases. Stopping a connection does not revoke remote account access or credentials.