> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcprouter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Router API

> The public router lifecycle and the boundary between selecting tools and calling them.

# 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](/integrate/models-servers-policies) and [security boundaries](/guides/security-and-trust).

| 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](/integrate/filter), [bindings](/integrate/model-bindings) and [scoped execution](/integrate/execute).

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](/reference/results-and-errors); 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.