6.7 Connect a read-only MCP tool

Use the reference service shipped with Teloa source to discover tools, read content and verify denials. It uses stdio, calls no model and reads no private directories. For an HTTP MCP service, use the complete app tutorial.

Prepare the files

Use Node.js 24 and a Teloa source directory whose dependencies are prepared through local development. The service entry is packages/mcp-reference/src/main.ts.

Download the complete client, extract it, then run inside the example directory:

npm install
node reference-client.mjs /absolute/path/to/teloa

Replace the argument with your actual absolute Teloa source path. The client starts and closes the service. A manually started stdio service waits for MCP messages and has no chat prompt.

How the client reads

reference-client.mjs includes imports, connection and cleanup. Its core call is:

const listing = await client.callTool({name: 'list_references', arguments: {}})
const ref = listing.structuredContent.references[0]
const read = await client.callTool({
  name: 'read_reference',
  arguments: {id: ref.id, version: ref.version},
})
console.log(read.structuredContent.text)

The list returns published IDs, sources and SHA-256 versions. Use that version when reading. The client prints actual reference text and its version, then three rejected requests.

Test	Expected result
List references	IDs workbench and capabilities
Read an ID and version from the list	Content, source and the same version
Unknown ID	reference/not-found
Wrong 64-character version	reference/version-conflict
Extra path argument	Validation failure without reading the path

Run the service's protocol tests from the Teloa source root:

pnpm test:references

Use it with an employee

The default composition registers teloa_reference. Check that it is connected, then select the actually discovered read tools for a test employee. Pause the employee, update its grant and resume before creating a new test task. Current full tool names are mcp__teloa_reference__list_references and mcp__teloa_reference__read_reference.

First verify denial without the grant, then successful reading after granting it. Inspect actual calls and receipts in the trajectory. A passing protocol client proves the service boundary; employee access also requires role and task authorization.

Adapt the service

Maintain an explicit server-side allowlist. Accept reference IDs and versions rather than arbitrary paths. List before reading; if content changes, require the caller to inspect the new version. Also test missing files, invalid encoding, oversized content, withdrawn access and stopping.

Implementation is in packages/mcp-reference/src/server.ts and catalog.ts. Test service-account and object access through the authorization guide before connecting a business system.