# Connect an agent

Connect through a compatible HTTP MCP client, discover the advertised tools and instructions, then follow the [catalog-first quickstart](/agents/quickstart/). The marketing website at `https://testril.si/` hosts documentation; it is separate from the service endpoint.

## Obtain the endpoint

The supplied captures use `https://dev.testril.ai/mcp`, with USDC payments. See
the [captured Workflow examples](/agents/workflow-examples.md). This identifies
the recorded service; confirm access requirements with the operator before
integration. `<MCP_URL>` in generic examples is a placeholder; do not infer an
endpoint from the website domain.

The implementation exposes an HTTP MCP route at `/mcp`. A self-hosted daemon's documented local default is `http://127.0.0.1:8000/mcp`. This loopback URL refers to your own machine, not the hosted Testril service.

## Discover the live contract

Use your MCP client's connection lifecycle, then request `tools/list`. Save the advertised tool names, input schemas, output schemas, and server instructions. The implementation supports the legacy initialize lifecycle as well as a stateless protocol generation; let a compatible client negotiate its supported version instead of guessing transport metadata.

The reviewed Testril 0.14.0 source and live discovery advertise nine public tools: `health_check`, `inspect`, `bind`,
`ask`, `materialize`, `read`, `provenance`, `stop`, and `claim_rewards`.

Read-only development discovery reported version 0.14.0 with those same nine
names, input-field names, and requiredness on 2026-11-02. Its live descriptions, schemas, and
instructions remain authoritative. The website's
[MCP service card](/.well-known/mcp.json) provides a directory entry point to
this development endpoint; it does not replace `tools/list`.

Priced `materialize` and `read` calls use x402 on the call itself; there is no
separate payment tool. Administrative operations are outside this public
reference; do not infer access from the public MCP endpoint.

If the deployed list differs, use the deployed schemas and report the mismatch to the operator. Do not call an unadvertised tool.

The current release review is recorded on the [agent reference](/agents/).
It combines a 0.14.0 source-tag review with read-only development discovery;
the exact deployed Git revision remains unconfirmed.

The earlier release review on 2026-10-13 checked the 0.9.0 release notes, public wire
types, handlers, tests, and served instructions at backend PR
[`ormi-labs/testril#274`](https://github.com/ormi-labs/testril/pull/274), commit
`319b8eb3c4ae94475b189f0015e9ade30c043fda`. The target release was not deployed,
so its MCP endpoint could not be rechecked through `initialize` or `tools/list`.
No metric work, write, or payment was performed. See the
[release review](/agents/).

## First calls

```json
{"tool":"health_check","arguments":{}}
```

```json
{"tool":"inspect","arguments":{"subject":"chains"}}
```

```json
{"tool":"inspect","arguments":{"subject":"functions"}}
```

The `{tool, arguments}` objects throughout this reference are **documentation notation**, not raw MCP transport messages. Invoke the named tool with those arguments through your client. Chain support is deployment-specific: a marketing coverage number does not establish which RPC providers a particular server has configured.

## REST data reads

A bound-function card names its one HTTP route in `data_endpoints.data`:
`GET https://dev.testril.ai/v1/bound_functions/{id}/data`, where `{id}` is the
returned `sha256:<hex>` identity. Put the read window and each row-key part in
query parameters. An unpaid request returns HTTP 402, a `PAYMENT-REQUIRED`
header, and the quote object in the body. Retry the same GET with the x402
payment in `PAYMENT-SIGNATURE`; a successful paid response carries
`PAYMENT-RESPONSE`. A signature that is not base64 JSON returns 400; a decoded
value that is not a payment returns 402 `invalid_payload`; reusing a
payment-identifier for another request returns 409. There is no quote, status,
provenance, write, or OpenAPI route; writes stay on MCP. Do not construct any
other `/v1` path.

The REST quote uses the same 0.9.0 money contract as MCP: ordinary money fields
are `{atoms, usd}` objects. x402 `accepts[].amount` remains a bare atom string.

## Record an integration fingerprint

Store the endpoint, negotiated protocol version, discovered tool schemas, configured chain IDs, and the time of discovery. Recheck after server upgrades. Keep authentication and RPC credentials outside logs and prompts; inspect and provenance data should be sufficient without exposing a provider's secret URL.