Tools
Anything that speaks MCP goes in tools/, one file per service:
// 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:
// 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.
// 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: 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:
// 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:
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:
// 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).