MCP client

This is the other direction to MCP server, which exposes this deployment's tools to an external client. Here, an external MCP server's tools become tools of this agent: they land in the same ToolRegistry that @aiTool discovery writes to, so an imported tool goes through every gate a hand-written one does — the RolesPolicy, the persona/agent allow-list, and input validation.

import { defineConfig } from '@adonis-agora/agent'

export default defineConfig({
  // ...
  mcpServers: [
    { name: 'github', transport: { type: 'stdio', command: 'mcp-github' } },
    {
      name: 'search',
      transport: { type: 'http', url: 'https://mcp.example.com', headers: { authorization: `Bearer ${env.get('MCP_TOKEN')}` } },
    },
  ],
})

What each server's config controls

A name belongs to whoever claimed it first

The registry is keyed by name and nothing else, so an un-namespaced import would let a remote server's search silently replace the app's own — a substitution invisible from everywhere else, because the model goes on calling search and search now reaches somebody else's server. So imported names are prefixed with the server's name by default, and a second claimant on a name is refused with a warning naming both claimants, never allowed to replace a live handler.

That applies between servers too, and the answer is stable: listing runs in parallel because the servers are independent, but registration replays in configuration order, so a contested name goes to the server configured first however fast the other one answered.

Names are also reshaped to the tightest tool-name rule among the major model providers (^[a-zA-Z0-9_-]{1,64}$) — an MCP server is under no such constraint, and repo/create.issue is a legal MCP tool name. The result is stable across restarts, including when it had to be truncated, because a stored tool call in a thread refers to a tool by this name.

A server that is down costs its own tools

Booting the whole application on the availability of a third-party process is the wrong trade, so an unreachable server is reported and skipped: the model is simply never offered its tools. required: true says the app is not useful without that server and should fail loudly instead.

A server that was down at boot is not lost — the importer's refresh(name) re-imports from it, and re-importing a server it already registered from does not collide with itself.

A refresh removes as well as adds

refresh() is the server's current answer to tools/list, not an addition to what it once said. A tool the server has dropped or renamed is unregistered: it stops being offered to the model, and calling it raises ToolNotFoundError here instead of failing on somebody else's machine several seconds later. Only names this importer registered for that server are eligible — never the application's own, never another server's — and a freed name is claimable by the next server in configuration order within the same refresh.

A server that could not be reached prunes nothing. Its tools are unknown, not gone, and a network blip is not a reason to withdraw a working tool from the model.

refresh(name) for a name no open server matches warns and returns 0, rather than leaving a 0 that reads identically to a server which answered with no tools.

Two things a remote schema can do to this process

Both end with the tool dropped rather than imported with a permissive stand-in, because the alternative would let the model send that remote tool arbitrary arguments under the appearance of a validated call:

• A schema that will not compile. Validation is the server's real schema, not an approximation: ToolSpec.inputSchema wraps it as a Standard Schema and hands the document back verbatim, which is what makes the model see the real parameter shapes.
• A pattern that can backtrack exponentially. Every validator in the MCP SDK compiles pattern to a native RegExp, and JS regex matching backtracks: (a+)+$ against 27 as and a non-matching tail takes ~1s, 30 ~8s, 40 longer than anyone will wait — synchronously, on the only thread the process has. The pattern is written by the remote server and the string is written by the model, whose steering the same server's tool description is free to supply, so the whole thing fits inside one tool definition. The screen is structural rather than a decision procedure; a host that wants a guarantee gives validator an engine that does not backtrack (AJV's code.regExp option takes an RE2 binding).

The connection is not durable state

A remote server may restart, be redeployed, or drop an idle connection, and the first symptom is a failed tool call. So a call that fails transiently drops the client, and the retry reconnects on its next attempt. The retry is invokeWithTransientRetry — the same in-place retry the loop wraps every tool with — so under the durable runner a reconnect never becomes a second checkpoint.

A tool that answered isError failed on its own merits and is never retried: its message is text the remote server wrote, and matching that against transient markers would let a tool's prose decide whether this side retries.

An approved action is never issued twice

A request timeout, a dropped connection, a reset mid-flight, a 500/502/503 — every one of those is also what a remote tool that ran looks like when its reply is lost. Re-issuing on one would spend a single human approval on two remote side effects, and nothing on this side would ever know: an imported tool's effects happen on somebody else's machine, which is why they are HITL-gated in the first place.

So which classifier applies depends on the tool's kind:

Supplying your own classify takes that judgement over for every kind, action included. Both classifiers are exported from @adonis-agora/agent/mcp-client.

Reaching the importer directly

@adonis-agora/agent/mcp-client exports the pieces, for a host that wires its own boot or wants to review what a server supplied:

import { McpToolImporter } from '@adonis-agora/agent/mcp-client'

const importer = new McpToolImporter(servers, registry, logger)
await importer.start()
importer.importedTools() // [{ name, serverName, remoteName, description }]
await importer.refresh('github')
await importer.close()

description is worth reviewing: it is text a third party wrote that rides into the tool list of every turn.