# Tools

Anything that speaks MCP goes in `tools/`, one file per service:

```ts
// tools/ledger.ts
import { tool } from "@praecise/harness";

export default tool({
  url: "https://ledger.example.com/mcp",
  credential: "LEDGER_TOKEN",
});
```

Then `tools: ["ledger"]` on any agent, and `LEDGER_TOKEN` in `.env`. Leave
`credential` off and it reads `LEDGER_API_KEY`, after the filename.

There is no built-in list of known services. A hard-coded endpoint is someone
else's URL to change and someone else's product to retire; four lines in your
own repo say plainly what your app talks to.

A service that is listed but unconfigured does not break the app — the dashboard
says which key is missing and the agent runs without it.

## A local program, or an ordinary API

A large share of published MCP servers are programs you launch rather than URLs
you call, and most APIs worth reaching have an OpenAPI description and no MCP
server at all. Both are services here:

```ts
// tools/files.ts — a program, spawned without a shell
export default tool({ command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] });

// tools/stripe.ts — an ordinary HTTP API, described
export default tool({ openapi: "https://api.example.com/openapi.json", credential: "ACME_KEY" });
```

An OpenAPI document becomes one tool per operation, with the parameters flattened
into the single object a model produces and each value's location remembered — so
the model does not have to know which of its arguments are a path segment, a query
string, a header, or the body.

## Code mode

An agent with many tools, or one that chains calls, does better writing a program
than making calls one by one. Turn on `code` and the agent gets a single `code`
tool instead of one per operation: its services appear as a typed API in the
tool's description, the model writes a short program against it, and only the
program's result comes back into context.

```ts
// agents/analyst.ts
export default agent({
  role: "Answers questions that need several systems at once.",
  tools: ["crm", "billing", "acme"],
  code: true,
});
```

The program runs in a [Praecise Silo](https://praecise.com/silo): a microVM with no
network, whose only way out is the agent's services. Each HTTP service is bound into
it; the silo's host makes each call with the credential from `.env`, so the key never
enters the program's world. An MCP server becomes `tools.<service>.<tool>(args)`; an
OpenAPI service becomes `tools.<service>.request({ method, path, query, body })`,
with its document in `spec.<service>` for the program to search — a large API never
has to fit in the prompt. A service launched as a local program cannot be bound and
stays an ordinary tool beside `code`.

`code: true` reaches the silo service named by `code: { silo }`, else by
`PRAECISE_SILO`, else its local socket: a `unix:` path on the same machine, or an
`https://` address reached with the agent token in `PRAECISE_SILO_TOKEN`.
`code: { language: "python" }` asks for Python (`"javascript"` also works); the
default is TypeScript. One silo is kept per agent for its term, `ttl` seconds
(default 1800), and replaced when it expires.

`code: { allow: { acme: ["GET /things/*"], crm: ["find_contact"] } }` narrows what the
program may call, by service: tool names for an MCP server, `"METHOD /path"` patterns
for an OpenAPI service. The silo refuses anything else before it leaves the host and
logs every call, allowed or not.

## More tools than fit in a list

Every tool an agent is shown is read on every request. When an agent's services
publish more than a dozen tools and their definitions pass a tenth of the endpoint's
`room`, they are not listed. The agent gets `find_tools`, which answers a
description of a job with the best-matching tools and their arguments, and
`use_tool`, which calls one by name. A call made through `use_tool` is checked by
`guard.ts` and recorded as a call to the tool it names. Your own functions are
always listed.

## Servers that want a token you do not have yet

A hosted MCP server is usually an OAuth 2.1 protected resource, and answering its
challenge needs a browser, a callback, and somewhere to keep tokens — three things
a framework should not decide for you. praecise implements the protocol and leaves
those to you: it recognises the challenge, hands it to your `authorize` callback,
and retries the request once with whatever you return.

`OAuthClient` covers the flow itself, including the parts that exist because of an
attack rather than a feature — the `resource` parameter on both requests so a token
minted for one server cannot be spent at another, byte-exact issuer validation, PKCE,
and registrations that are never presented to a server that did not mint them.

Where the authorization server supports Client ID Metadata Documents, set
`clientMetadataUrl` to the HTTPS address of a document your app hosts and that
address is used as the client id, with no registration request.
`clientMetadataDocument()` builds the document. Without the option, or on a server
that does not support it, the client registers dynamically as before.

Two grants need nobody at a keyboard, and a service names one in its file:

```ts
// tools/ledger.ts
export default tool({
  url: "https://ledger.example.com/mcp",
  oauth: {
    grant: "client_credentials",
    issuer: "https://auth.example.com",
    clientId: "acme-app",
    secret: "LEDGER_CLIENT_SECRET",
  },
});
```

`client_credentials` is the app acting as itself, with a secret or a private key
(`key`) it signs an assertion with. `grant: "id-jag"` is enterprise-managed
authorization: the identity provider at `idp` is asked, on the strength of the ID
token named by `assertion`, for a grant the server's authorization server
exchanges for a token. `secret`, `key` and `assertion` are names of environment
variables, never the values. `issuer` is required, and the grant is made there or
not at all. A service declared this way has one identity; an app that serves
many people calls `exchangeIdentity` and `redeemGrant` on `OAuthClient` for each
of them. The `id-jag` grant follows a specification that is still a draft.

## What an MCP server may ask of the app

**Something from a person, mid-call.** A server may ask for a value (a form) or
send the person to a page (a URL). The app answers through `mcp.elicit`:

```ts
const app = await App.load({
  root,
  mcp: {
    elicit: {
      form: async ({ service, message, schema }) => ({ action: "accept", content: await askPerson(message, schema) }),
      url: async ({ service, url, host }) => ({ action: "decline" }),
    },
  },
});
```

Each mode is declared to a server only when its handler is there, so a server
never asks for what nothing can answer. The URL is handed to the app and never
fetched. A call may be asked for more input eight times running.

**To be told when its tools change.** `watch: true` on a service keeps a
`subscriptions/listen` stream open and lists the server's tools again when it
says they changed.

**To offer its skills.** `skills: true` on a service, or a list of
`skill://` addresses, offers agents the skills that server serves, read through a
`read_service_skill` tool. Each file is checked against the server's manifest by
SHA-256, marked with where it came from, and treated as that service's output.
Nothing in a skill is executed.

**To show a view.** A tool may bring an interactive page with its result (an MCP
App). With `mcp: { apps: true }` the page is read from the service and handed on
as `answer.ui`, and as an `ACTIVITY_SNAPSHOT` over AG-UI, for a front end to
render in a sandbox of its own. What the page asks for (`tools/call`,
`resources/read`, `ping`) is forwarded to `POST /api/ui/<service>` and goes
through `guard.ts` with `via: "ui"`. The frame, its sandbox and the messages
into it are the front end's.

MCP roots, sampling and logging are not offered: the revision of the protocol
spoken here deprecates all three.

## A screen as a tool

`computer` turns a screen into a function an agent can call, and `browserScreen`
is the screen that ships, a Chromium the app points to:

```ts
// functions/browser.ts
import { browserScreen, computer } from "@praecise/harness";

export default computer(await browserScreen({ executable: "/usr/bin/chromium", url: "https://example.com" }));
```

The agent takes screenshots and clicks, double-clicks, moves, drags, scrolls,
types, presses keys, waits and zooms. The function is `effect: "write"` and its
output is untrusted, so the guard sees every action and what is read from a page
taints what follows. An endpoint that has a computer tool of its own names its
type as `computer` on the endpoint, and on the `messages` shape the tool is sent
as that; everywhere else it is sent as an ordinary function. Any other screen is
an object that implements `Screen`.

`computer(screen, options)` takes the tool's `name` (`computer` by default), an
`about` sentence on what the screen is, `screenshotAfter: true` to return a
screenshot with every action that can change the screen (off by default, after
`settleMs`, 400 by default), and `maxWait`, the longest one wait may be in
seconds (30 by default).
