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

# Install a development candidate

> Obtain an unpublished, verified archive without assuming a public npm release.

# Install a development candidate

> **Public documentation preview — incomplete.** The SDK and optional AI SDK peers are private and unpublished. This page does not provide an archive, public registry release or permission to make live provider requests.

The package is currently `private: true` and versioned `0.0.0-development`. **Do not run `npm install @surf-lab/mcprouter` against the public registry and expect this candidate.** Obtain an approved archive from the maintainer, with its expected SHA-256 hash and dependency provisioning instructions. Installation does not authorize provider requests, publication or access to MCP servers.

The package declares ESM with Node.js `>=22.3.0` and npm `>=10.9.0` on compatible pairs; accepted consumer examples target Node 22 and 24. This declaration is not blanket OS/version certification. Before installing, verify the archive against the maintainer's record. For example, on a system with `shasum`:

```sh theme={null}
shasum -a 256 /absolute/path/to/approved-candidate.tgz
# Compare the printed digest with the maintainer's recorded digest.
npm install --ignore-scripts /absolute/path/to/approved-candidate.tgz
```

Replace the path and verify the digest **before** executing the install command. Use a fresh ESM consumer and provision dependencies first; offline tests must deny external networking during execution, not silently fall back to a registry. Imports must resolve from the installed archive, not the source tree or a `dist` alias.

```js theme={null}
import { createRouter } from '@surf-lab/mcprouter';
```

Core calls need no AI SDK peer, model, key or download. The optional `@surf-lab/mcprouter/ai-sdk` subpath currently requires the separately supplied private `ai@7.0.137-mcprouter.2` peer; the example OpenAI-compatible provider uses private `@ai-sdk/openai@4.0.91-mcprouter.2`. Obtain verified, compatible peer archives through your maintainer; public registry versions are **not** assumed interchangeable.

## Planned default or patched choice

The intended release will offer a choice of **default upstream SDKs** or **opt-in patched replacements**, not require every application to install both. This dual-option support is **not yet implemented or validated**: the current package still pins the private `ai` peer above.

The selected npm names for the future patched packages are:

| Planned package | Replaces | Application import name when installed through an npm alias |
| - | - | - |
| `@surf-lab/mcprouter-patch-ai` | The upstream `ai` SDK | `ai` |
| `@surf-lab/mcprouter-patch-openai-sdk` | The upstream `@ai-sdk/openai` provider | `@ai-sdk/openai` |

**These are selected names, not published or install-ready packages.** Availability, release versions, final artifact qualification and publication are still pending. No public install command for them is provided yet. The OpenAI provider here is `@ai-sdk/openai`, not the separate `openai` npm client; other providers need their own compatibility checks.

* **Core only:** no AI SDK dependencies are needed.
* **Default option, planned:** an app would keep its existing supported `ai` and provider versions and use the mcprouter integration. Having those dependencies installed does not yet establish compatibility with this development candidate.
* **Patched option, planned:** an app would explicitly choose the patched replacements. Aliases can preserve its existing `ai` and `@ai-sdk/openai` imports, but replace the dependencies behind those names for the app—not only for mcprouter. They are prepatched packages, not scripts the consumer must apply.

Do not install two versions under the same dependency key or assume isolated copies interoperate. Supporting both choices across applications does not mean automatically installing or loading both in one application.

### TypeScript compatibility boundary

The public versions tested on October 20, 2026—`ai@7.0.146` and `@ai-sdk/openai@4.0.98`—fail the strict declaration check with TypeScript 5.9.3. Their shared `@ai-sdk/provider-utils` tool types disagree about optional properties and explicit `undefined`. The existing private patch corrects a type declaration; it does not change runtime JavaScript or OpenAI API behavior. This finding does not prove the upstream runtime is broken, and it is not a claim about every future release.

The project keeps `strict`, `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess` enabled, with `skipLibCheck: false`. A supported default profile still needs a validated solution to the declaration issue; it is not made compatible simply by documenting a choice. Consumers use their own compiler settings, so relaxing the library's checks would not repair upstream declarations for them.

### One package, one integration subpath

The main package remains **`@surf-lab/mcprouter`**. Its existing **`@surf-lab/mcprouter/ai-sdk`** subpath contains the integration code; it is not one of the two planned patched dependency packages. There is no `/openai` or `/ai` integration export.

A subpath selects code to import, not a separate npm installation. Importing `/ai-sdk` does not download its peers. The current optional-peer design keeps core-only installations free of the AI SDK. Selecting a patch package name does not change that design or publish an artifact.

After installing, try a [synthetic first governed call](https://docs.mcprouter.dev/start/first-call.md). See [integration choices](https://docs.mcprouter.dev/start/choose-integration.md) before setting up a model or a remote MCP endpoint.


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