Router API

Public documentation preview — incomplete. The SDK and optional AI SDK peers remain private and unpublished. This orientation is not the exhaustive, release-qualified API reference.

Import createRouter from @surf-lab/mcprouter. It returns an instance-local Router and does not connect to MCP servers, run a model or dispatch a tool at construction. RouterConfig accepts limits?, policy?, ranker?, models?, model? and audit?; a string model names a configured routing adapter, not a provider. See trusted policy and security boundaries.

Method	Input	Return	Meaning
`registerTools(bindings)`	Local registrations (`localKey`, descriptor, handler)	Bound descriptors	Register application-owned handlers; no model request
`unregisterTools({ toolIds })`	Registered tool IDs	`void`	Retire local bindings; previously held descriptors can become stale
`connectServers(configs, options?)`	Trusted `ServerConfig[]`; optional signal/timeout	`void`	Connect stdio or Streamable HTTP servers owned by the router
`disconnectServers({ serverIds, ... })`	Server IDs and optional signal/timeout	`void`	Remove server bindings; refresh selected inventories
`discover({ refresh?, ... }?)`	Optional explicit refresh, signal and timeout	Bound descriptors	Inspect current registered tools and server inventories
`filterTools({ prompt, tools?, model?, ranker?, context?, ... })`	Selection options	`RankedTool[]`	Retrieve without dispatch; lexical unless a ranker or named `.ranking` adapter is chosen
`call({ toolId, arguments, expectedSnapshot?, context?, ... })`	Exact tool ID and JSON arguments	`ExecutionResult`	Governed exact call; no model inference
`execute({ prompt, tools?, model?, context?, ... })`	Intent and selected sources	`ExecutionResult`	Propose, validate and potentially dispatch at most one call
`close()`	None	`void`	Release instance-owned resources in `finally`

FilterToolsOptions prohibits supplying model and ranker together. ExecuteOptions.model is a routing selector or explicit adapter, independent from retrieval ranking. The shared tools input can contain trusted server configs, bound/unbound descriptors or raw MCP definitions; raw definitions are not executable just because they were filtered. Omitted selection sources use the router’s currently known tools; explicit sources do not silently widen to all registered servers. See filtering, bindings and scoped execution. Options may reject malformed configuration with RouterConfigError. Operations can reject with RouterOperationError, or call/execute can return a non-success ExecutionResult. Always inspect both the outcome and side-effect state; a score from a ranked result is not a field in an executable source descriptor. This is an orientation page, not yet the exhaustive field/default/type reference required for the final documentation release.

Get started

Integrate

Guides

Reference

Router API

Router API

​Router API

Router API