---
title: Connect a read-only MCP tool
description: Use a complete client to read a reference and verify rejected requests.
lastVerified: 2026-10-22
---

# 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](https://docs.teloa.ai/v/0.2.7/markdown/en/develop/apps.md).

## Prepare the files

Use Node.js 24 and a Teloa source directory whose dependencies are prepared through [local development](https://docs.teloa.ai/v/0.2.7/markdown/en/develop/local-development.md). The service entry is `packages/mcp-reference/src/main.ts`.

[Download the complete client](https://docs.teloa.ai/v/0.2.7/examples/developer-toolkit-024.zip), extract it, then run inside the example directory:

```sh
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:

```js
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:

```sh
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](https://docs.teloa.ai/v/0.2.7/markdown/en/develop/permissions.md) before connecting a business system.