MCP
Declare remote MCP servers the Runtime discovers for a session.
Declare MCP servers with .mcp(). The map shape matches Agent Plugins
mcpServers; a server's name defaults to its key.
import { Agent } from "@nylorun/agents";
export const assistant = Agent({ id: "assistant", name: "Assistant" })
.instructions("Use the available tools.")
.mcp({
github: { type: "streamable-http", url: "https://mcp.example.com/github" },
});Nylorun accepts remote servers only: streamable-http and sse
(Agent Plugins MCP servers),
declared by URL and reached through the Runtime's gateway. To use a server that
speaks stdio, run it behind an HTTP transport and declare its URL.
| Field | Value |
|---|---|
type | "streamable-http" or "sse". |
url | The server's URL. |
headers | Optional request headers. They are part of the manifest, so put credentials in a secret slot instead. See Credentials. |
tools | Optional. Settings per tool. See Per-tool settings. |
deferred | Optional. true or false defers every tool of the server, or none. See Deferred tools. |
A server key must match ^[A-Za-z0-9_-]{1,64}$; saving the agent manifest
refuses any other (400, naming it). Calls merge into the harness section's
mcpServers: .mcp({ github }).mcp({ docs }) declares both servers. Server
names are unique among the agent's servers, a plugin's
included. A server a plugin brought carries plugin: { name, version } in the
manifest, and mcp.discovered and each of its tool calls name that plugin.
The Runtime discovers each server's tools on the session's first turn and pins
them for the session, by the names the servers give them, disabled tools
included. The pinned list contains no secrets. mcp.discovered reports each
server's outcome and how many enabled tools it added; see
Events. A server that failed or was refused at the first
turn is tried again at each later turn's start, never mid-turn; once it
answers, its tools join the session's from that turn on, and a second
mcp.discovered names it with rejoined: true.
The harness names the tools for the model. Our harness calls each one
<server>__<tool>, with characters outside [A-Za-z0-9_-] replaced by _: a
server tool issues.create on github is github__issues_create. A name over
64 characters, or one that collides, keeps 55 characters and gets _ and a
hash suffix. A name one of the agent's own tools already has leaves the server
tool out. The server is still called with its own tool name, and the tool
policy and tool.completed name the tool by server and its own name (tool).
Credentials
A server's credential is a secret of the Agent the session
runs on: a bearer or headers secret bound to the server's URL, sent with
every request to it. A server with no matching secret is called without one.
Nylorun does not sign in to MCP servers with OAuth: add the server's key, or
reach it through a gateway. See
Secrets and credentials.
To make the slot part of the manifest, name it as ${NAME} in a header of an
agent manifest's mcp.json:
{
"mcpServers": {
"github": {
"type": "streamable-http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
}
}
}The header becomes credential on the server in the harness section. When
runtime.json does not declare the slot, the compiler derives a bearer slot
bound to the server's exact URL and says so:
$ npx nylorun check triage
triage/mcp.json:6:37 info: A bearer slot GITHUB_TOKEN is derived for https://api.githubcopilot.com/mcp/
triage: ok, agent manifest triage (2 files, agent-folder/1)When it does declare it, nylorun check and the save check that it is a
bearer or headers slot of that name bound to the server's exact URL, and
refuse a gap (422 manifest_inconsistent from the save). The builder's
.mcp() takes no credential, so a server declared in TypeScript matches the
Agent's secrets by URL alone. See
Secret slots.
In the deprecated three-file format,
a harness file's credentials map names the slot instead:
{
"$schema": "https://docs.nylorun.com/schemas/harness-manifest/v1.2.json",
"instructions": ["Triage the GitHub issue the user names."],
"mcpServers": {
"github": {
"name": "github",
"type": "streamable-http",
"url": "https://api.githubcopilot.com/mcp/"
}
},
"credentials": { "github": "GITHUB_TOKEN" }
}Through a gateway
A credential with via sends the server's requests to a gateway, such as
LiteLLM, instead of the server's URL. A gateway that lists each tool under a
prefix of its own (LiteLLM's github-create_issue) needs toolPrefix on the
Agent's credential: the Runtime takes the prefix off, so tool names
(github__create_issue), the server's tools settings, and tool policy rules
name the server's own tools, whether or not a gateway is in between. The
manifest never names toolPrefix; it is written with the Agent's secret. See
Gateway tool prefix.
An agent that has only MCP servers and HTTP tools needs no sandbox: save it
with a runtime of kind none (or no runtime section), and its Agent holds
secrets and no compute. The gateway follows the same address rules as for
HTTP tools: on a local Tenant, localhost
means your machine.
List a server's tools, and the names the model would see, before you declare it:
npx nylorun tenant mcp inspect https://mcp.example.com/github --server github --agent projects/acme--agent sends that Agent's credential for the URL; without it the server is
called with none. See
Preview an MCP server.
Per-tool settings
tools maps the server's own tool names, as its docs show them, to settings.
"*" applies to every tool without an entry.
Agent({ id: "triage" }).mcp({
github: {
type: "streamable-http",
url: "https://api.githubcopilot.com/mcp/",
tools: {
"*": { enabled: false }, // only the tools below
search_issues: { enabled: true },
create_issue: { enabled: true },
},
},
});| Setting | Value |
|---|---|
enabled | false: the tool never reaches the model and is never called. Default true. |
deferred | true or false overrides the automatic choice. See Deferred tools. |
Each setting resolves from the tool's entry, then "*", then the server, then
the default. A key that names no tool the server lists is not an error:
mcp.discovered reports it in unknownTools, and counts disabled tools in
disabled. A call of a disabled tool fails with tool.disabled and is never
sent.
Which calls wait for a person is not a server or tool setting: the Tenant's
tool policy decides it. A rule names an MCP tool by
its server and its own name, { "server": "github", "tool": "create_issue" };
a rule whose tool has __ in it, such as github__create_issue, is refused.
approval on a server or a tool throws, and saving an agent manifest that sets
it is refused. In an agent manifest, approval under AGENT.md's
mcpServers.<server>.tools is an approval_removed error that nylorun check
reports at its line.
Deferred tools
The harness decides which MCP tools the model sees at once. An
agent-folder/2 agent's are
deferred automatically only when it declares engine.toolSearch: true; without
it, they all stay in the tool list, and a session past the threshold records an
engine.diagnostic event (mcp_tools_inline). Otherwise, when an agent's MCP
tools would take more than a tenth of the model's context window (names,
descriptions, and input schemas, at 4 characters a token), our harness takes
them out of the model's tool list. The model gets two tools instead, and a note
naming each server and how many of its tools are deferred:
| Tool | Input | Role |
|---|---|---|
tool_search | { query, limit? } | Finds deferred tools by words of their names and descriptions. Returns 8 by default, at most 20, each with name, description, and inputSchema. |
tool_call | { name, arguments? } | Runs one deferred tool. |
Both run in our harness (kind: "harness"). A tool_call makes the tool's own
call: the tool policy decides it as it decides the tool, and tool.completed
names the tool, not tool_call. deferred on a tool, on "*", or on the
server decides instead of the size rule. The choice is made once per session,
so the model's tool list is the same at every step. When tools are deferred, an
agent's own tool named tool_search or tool_call fails the turn.
The context window is the Tenant model's, or 32,768 tokens when it is unknown.
See Models. These numbers are our harness's defaults; a
harness built on our engine sets its own with createHarness({ mcpTools }).
Large results
Our harness stores a remote MCP or HTTP tool result over 32 KiB, and every
image, audio, or file part of an MCP result, as a file artifact of the session.
The model gets a preview (the first 4 KiB and the last 1 KiB) and the
artifact's id, and reads on with the built-in read_artifact tool
({ artifactId, version?, offset?, length? }, up to 32 KiB a call). Every
session has read_artifact, with or without a sandbox.
These artifacts count toward the Tenant's artifact limits. An answer over the
Tenant's Runtime limit toolAnswerBytes (8 MiB by default) is not kept: the
call fails with mcp.too-large (http.too-large for an HTTP tool). See
Files.
Errors
A failed call gives the model a failed tool result with a code, a message,
and retryable. tool.completed's error records the same.
| Code | When | Retryable |
|---|---|---|
credential_rejected | The server, or the gateway at via, answered 401, or the gateway reported that the server behind it answered 401 (LiteLLM's auth_required). For a workload credential, error.gateway names the gateway's origin. The Runtime never retries it. | No |
mcp.unreachable | The call was never sent: a refused address, DNS, a refused connection, or TLS. | Yes |
mcp.forbidden | The server answered 403. | No |
mcp.error | A JSON-RPC error, with its code in the message. | No |
mcp.status | Another HTTP error status. | For 408, 429, 502, 503, 504 |
mcp.lost | The call was sent and the answer lost, so the tool may have run. The model decides whether to call it again. | Yes |
mcp.too-large | The answer is over toolAnswerBytes (8 MiB by default). | No |
The Runtime delivers each call at least once. A tools/call carries the
call's key in _meta["nylorun/idempotency-key"], and the same key when a crash
or a restart inside the Runtime makes it send the call again, up to the
Tenant's Runtime limit toolAttempts (3 sends by default); after that the
model gets tool.interrupted. A server that honors the key
acts once. Each request of the call also carries a traceparent header; see
Traces. A call the tool policy refuses, or a
person denies, is tool.denied and never sent. See
Pauses and control.
A tool's own error result
(isError) is mcp.tool. A call of a tool the session did not discover is
tool.unknown, and of a disabled tool tool.disabled. tool_call answers
tool.unknown for a name no deferred tool has, and tool.invalid-arguments
for arguments that do not match the tool's input schema; nothing runs. A credential value that a server echoes
back is replaced with [redacted] before the model or an event sees it.
Declaring servers can fail too:
| Code | When |
|---|---|
mcp.stdio | A server declares type: "stdio". PUT /v1/agent-manifests/{name} refuses one too (400). |
mcp.name-mismatch | A name differs from its key. |
mcp.empty | The map is empty. |
mcp.duplicate-server | The same server is declared twice (a build failure). |
The first three throw McpError.