[!NOTE] This package is a migration-only compatibility facade. New code should import the canonical @openrouter/agent/mcp subpath. Existing @openrouter/mcp root and subpath imports remain functional and would only be removed in a future breaking release after migration notice.

Expose the tools of a remote Model Context Protocol server (Streamable HTTP or SSE) as tools you can pass straight into @openrouter/agent's callModel.

Connect to a non-stdio MCP server, authenticate once, and reuse that auth for tool discovery and every tool call.
Faithful JSON Schema → Zod conversion so the model sees real parameters.
Serializable, rehydratable cache so you can skip re-listing (and, opt-in, re-authenticating).
Progress streaming, tools/list_changed auto-refresh, cancellation, resources, and elicitation.

stdio servers are intentionally out of scope.

Install

For new code, install the agent plus the optional MCP peer:

pnpm add @openrouter/agent @modelcontextprotocol/client

Existing applications can keep installing only the compatibility package; it retains @modelcontextprotocol/client as a dependency, so the prior transitive-install behavior is unchanged:

pnpm add @openrouter/mcp

The agent package is marked sideEffects: false, and MCP code is exposed only through explicit /mcp exports. Root and /tool-set imports do not statically load MCP modules; the MCP SDK is not installed transitively for base agent users. The /mcp entry point also loads the optional SDK lazily: importing it is safe without the peer, while the first connection attempt throws an actionable MCPMissingPeerDependencyError when the SDK has not been installed.

Compatibility subpaths

Existing facade	Canonical replacement
`@openrouter/mcp`	`@openrouter/agent/mcp`
`@openrouter/mcp/create-mcp-tools`	`@openrouter/agent/mcp/create-mcp-tools`
`@openrouter/mcp/types`	`@openrouter/agent/mcp/types`
`@openrouter/mcp/schema`	`@openrouter/agent/mcp/schema`
`@openrouter/mcp/cache`	`@openrouter/agent/mcp/cache`

Quick start

import { OpenRouter } from '@openrouter/agent';
import { callModel } from '@openrouter/agent/call-model';
import { createMCPTools } from '@openrouter/agent/mcp';

const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const mcp = await createMCPTools({
  url: 'https://mcp.example.com/mcp',
  auth: { kind: 'bearer', token: process.env.MCP_TOKEN },
});

const result = callModel(client, {
  model: 'anthropic/claude-opus-4-8',
  input: 'What are my three most recently updated issues?',
  tools: mcp.tools,
});

console.log(await result.getText());
await mcp.close();

Authentication

Auth is supplied once and reused for discovery and every call:

// Static bearer token
auth: { kind: 'bearer', token }
// Arbitrary headers
auth: { kind: 'headers', headers: { 'X-API-Key': key } }
// Pluggable OAuth (you own token refresh/storage)
auth: { kind: 'oauth', provider }

Prefer an OAuthClientProvider over caching static tokens — the transport refreshes through it automatically.

Caching & rehydration

Persist a snapshot and rebuild later without a listTools() round-trip:

import { createMCPTools, rehydrateMCPTools } from '@openrouter/agent/mcp';

const mcp = await createMCPTools({ url, auth, cacheCredentials: true });
const snapshot = await mcp.serialize();   // plain JSON — store anywhere
await mcp.close();

const mcp2 = await rehydrateMCPTools({ snapshot, auth });

Or let a store manage it (rehydrate on hit, connect + write on miss):

import { InMemoryMCPCacheStore } from '@openrouter/agent/mcp';

const store = new InMemoryMCPCacheStore(); // or your own Redis/DB-backed MCPCacheStore
const mcp = await createMCPTools({
  url,
  auth,
  cache: { store, key: `mcp:${userId}` },
  staleness: { maxAgeMs: 60 * 60 * 1000 },
});

Security: cacheCredentials is false by default. When enabled, snapshots contain bearer tokens/headers — treat the store as a secret store and namespace cache keys by principal in multi-tenant setups.

Multiple servers

const [github, linear] = await Promise.all([
  createMCPTools({ url: githubUrl, auth: gh, toolNamePrefix: 'github_' }),
  createMCPTools({ url: linearUrl, auth: ln, toolNamePrefix: 'linear_' }),
]);

const result = callModel(client, {
  model,
  input: 'Find the Linear issue linked to GitHub PR #42.',
  tools: [...github.tools, ...linear.tools],
});

Options

Option	Description
`url`	Remote MCP server endpoint.
`transport`	`'streamableHttp'` (default, falls back to SSE) or `'sse'`.
`auth`	Bearer token, headers, or an `OAuthClientProvider`.
`toolNamePrefix`	Prefix every wrapped tool name.
`includeTools` / `excludeTools`	Allow/deny lists by MCP tool name.
`onUnconvertibleSchema`	`'looseLeaf'` (default) or `'throw'` for exotic JSON Schema.
`cache` / `cacheCredentials` / `staleness`	Caching controls.
`resources`	Expose synthetic `list_resources` / `read_resource` tools (default on).
`emitProgress`	Stream MCP progress as generator-tool events (default on).
`autoRefreshOnListChanged`	Re-list on `tools/list_changed` (default on).
`onElicitation`	Handle server elicitation requests; auto-declines when omitted.
`signal`	Abort signal threaded into every tool call.