​

Architecture: from intent to an authorized action

Documentation for v0.0.1. Additional guides and API reference coverage are being expanded.

Whitepaper revision 3 · October 27, 2026 · SDK scope: published 0.0.1 mcprouter is an enforcement and selection component inside an application. It does not own the application’s identity system, reasoning loop or infrastructure. This distinction determines both its integration paths and its limits.

​

MCP connects capabilities; the host owns the application

MCP gives clients a common contract for discovering and calling server tools. A search tool can sit in front of a database, an index or a business API; the agent consumes the declared tool contract rather than implementing that backend’s transport and storage logic. MCP servers can also expose protocol resources, but this paper concerns the SDK’s tool-discovery and execution paths, not a claim of complete MCP feature coverage. Figure 2. Conceptual deployment topology, not execution order. mcprouter sits inside the host, not between applications as a hosted gateway. The MCP connection reaches a server that owns its backend implementation. Local handlers need no MCP server. Arrows show the request direction; results return along the chosen path. Backend data is not necessarily an MCP resource endpoint. The protocol does not choose the application’s retrieval strategy, establish the user’s permissions or orchestrate a multi-step workflow. mcprouter adds selection and a governed dispatch path around that interoperability contract; it does not replace MCP or the server’s own authorization. Scheduling, durable state, approvals and recovery across calls remain host concerns.

​

Three paths share one execution boundary

filterTools is a separate, non-dispatching operation. It returns ranked descriptors, not permission to execute. Filtering may connect to selected MCP servers for discovery; an explicitly chosen provider-backed ranker may also make inference requests. “No tool dispatch” must not be read as “no network traffic.” The optional AI SDK integration adapts governed tools to a host-owned generation loop. Router model-access policy does not constrain the host’s direct generateText calls. The host must separately control their credentials, destinations, data exposure and spending.

​

Discovery and relevance before action

The host chooses local registrations, trusted MCP server configurations or tool descriptors. Raw tool definitions can participate in filtering without becoming executable. A bound descriptor identifies an actual tool connection; a schema hash and binding generation support stale-replacement detection. Eligibility policy determines which tools may enter selection. Ranking then estimates relevance within that permitted scope. The default ranker uses normalized BM25-style lexical matching. Optional embedding, language-model and custom rankers support other retrieval strategies; they are alternatives, not an automatic lexical-to-semantic-to-model cascade. Without a policy, no candidates are eligible and supported exact calls are denied. This execution default does not itself block network egress or the host’s own inference calls. Model-access restrictions require explicit host configuration. A shortlist limit controls how many results return, not how many tools a selected ranker examines. Narrowing sources and eligibility before ranking is therefore important for both work and exposure. Ranking scores are strategy-specific: they are neither interchangeable confidence estimates nor authorization tokens. The filtering guide documents precedence, thresholds and source-selection rules.

​

The execution sequence

The order below matters. execute resolves routing-model bindings and checks model access across eligible targets before ranking. If the scope resolves to multiple routing models, it requests narrower input rather than selecting a specialist through ranking. Setting limit: 1 does not bypass that ambiguity. Figure 3. Source-aligned v0.0.1 execution flow. Deadlines, cancellation, capacity and snapshot checks apply throughout but are condensed for readability. Ranking/provider failures also stop the operation. There is no automatic fallback to a different model or tool after denial. The model proposes a call, no_match or needs_input. The router validates the proposal against its candidate set and validates tool arguments. Bounded repair can address supported structural errors; missing required facts trigger clarification. Argument repair cannot silently switch to another tool once the repair target is fixed. An accepted proposal enters the same governed call path as an exact host call. That path checks supported schemas, arguments, the current binding and authorization before dispatch. execute and AI SDK ToolSet calls pass an expected snapshot. Direct callers must supply expectedSnapshot when they require stale-replacement detection; it is optional on direct calls. An approval-required result does not perform the action. The host must complete its approval workflow and revalidate the eventual call. Likewise, a routing-model preference cannot override a denied exact call. See bounded execution and outcomes and errors for the API contract.

​

Trust follows the host, not generated text

Tool descriptions, schemas, arguments and response text are data to inspect, not sources of authority. Prompt injection can influence model proposals; execution controls must therefore remain outside the prompt. Figure 4. Logical trust boundaries, not process isolation or a sandbox. The host controls configuration and policy. Model and tool content cannot grant authority. A local handler still needs appropriate operating-system and application controls. The host must bind authorization to the exact server, tool, arguments and tenant or resource. A read-only annotation does not grant access. Policy revisions must reflect permission changes, and credentials or executable destinations must never come from model output. The default AI SDK model-facing output includes status, code and tool ID rather than the full result payload. Trusted host code receives the full execution result and controls further disclosure. Applications should record useful operational identifiers without indiscriminately logging prompts, secrets or customer data. When a tool declares an output schema, the governed call validates successful structured content against it. This is not schema validation of every text or image payload; tool-error results follow their error path. An output-validation failure happens after dispatch and can return failed with completed effects. Structural checks establish neither factual truth nor freedom from malicious instructions.

​

Recover from uncertainty without repeating effects

ExecutionResult separates status from side-effect state. not_started means dispatch did not begin; completed records completed effects, not necessarily business success; unknown means the router cannot prove what happened after dispatch. A timeout can leave an external action completed even though the caller did not receive its result. For a write operation with unknown effects, investigate or reconcile before retrying. The host should use service-supported idempotency keys, durable operation records and business-level checks where appropriate. Neither a timeout nor a retryable flag creates a rollback or an exactly-once guarantee. Multi-step workflows amplify this distinction. A host can compose several governed calls, but must own ordering, state persistence, compensation and approval between steps. A DAG executor, automatic frontier-model escalation and browser automation are architectural possibilities outside the released execute contract, not hidden features of it.

​

Deployment choices and operational ownership

The optional audit callback exposes redacted terminal events with operation identifiers, status, code, stage, side-effect state and duration. It excludes result payloads, proposals and policy reasons. This is not full per-stage tracing or a durable audit store; the host supplies retention, correlation and monitoring. Configured limits bound catalogue and payload sizes, attempts, concurrency and waits. They do not make blocking host callbacks preemptible or guarantee cancellation of remote side effects. Applications should handle capacity failures and close the router in finally to release instance-owned resources. Core operation needs no AI SDK peer, model weights or credentials. The published package targets Node.js ESM, with the documented Node/npm compatibility limits. It is not a hosted service and does not claim browser or CommonJS support. Local handlers, MCP stdio processes and remote Streamable HTTP connections have different exposure and lifecycle risks. A host-supplied local inference adapter can keep that inference path local, but local execution alone does not establish zero egress. Remote tools, embedding services, telemetry and application logging can still transfer data. Explicit endpoint configuration, network controls and data-flow review determine the deployment’s actual boundary. Start with security and trust boundaries, then use the evidence assessment to decide what additional testing your environment requires.