# MCP (/docs/build/mcp)



Declare MCP servers with `.mcp()`. The map shape matches Agent Plugins
`mcpServers`; a server's `name` defaults to its key.

```ts
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](https://agent-plugins.org/plugin-authors/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](#credentials). |
| `tools`    | Optional. Settings per tool. See [Per-tool settings](#per-tool-settings).                                                              |
| `deferred` | Optional. `true` or `false` defers every tool of the server, or none. See [Deferred tools](#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](/docs/build/plugins)
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](/docs/run/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 [#credentials]

A server's credential is a secret of the [Agent](/docs/run/agents) 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](/docs/run/credentials).

To make the slot part of the manifest, name it as `${NAME}` in a header of an
[agent manifest's](/docs/build/agent-manifests#credentials) `mcp.json`:

```json title="triage/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:

```text
$ 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](/docs/run/agent-manifests#secret-slots).

In the deprecated [three-file format](/docs/run/agent-manifests#three-files),
a harness file's `credentials` map names the slot instead:

```json title="harness.manifest.json"
{
  "$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 [#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](/docs/run/credentials#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](/docs/build/tools#reachability): on a local Tenant, `localhost`
means your machine.

List a server's tools, and the names the model would see, before you declare
it:

```sh
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](/docs/run/credentials#preview-an-mcp-server).

## Per-tool settings [#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.

```ts
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](#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](/docs/run/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 [#deferred-tools]

The harness decides which MCP tools the model sees at once. An
[`agent-folder/2`](/docs/build/agent-manifests#engine-features) 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](/docs/run/models). These numbers are our harness's defaults; a
harness built on our engine sets its own with `createHarness({ mcpTools })`.

## Large results [#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](/docs/run/files).

## Errors [#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](/docs/run/traces#trace-context). A call the tool policy refuses, or a
person denies, is `tool.denied` and never sent. See
[Pauses and control](/docs/run/control#tool-call-delivery).

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`.

## Next step [#next-step]

<Cards>
  <Card title="Skills" description="Load an Agent Skills catalog." href="/docs/build/skills" />

  <Card title="Secrets and credentials" description="Write a key for an MCP server into an Agent's secrets." href="/docs/run/credentials" />
</Cards>
