9Router MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@9Router MCP search the web for the latest Node.js 22 release notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Use your 9Router search, fetch, chat, vision, image, speech, embedding, and video capabilities from an MCP client. The server runs over stdio and forwards requests to your configured 9Router instance. Provider credentials, quotas, and fallback combinations are managed in 9Router.
flowchart LR
A[MCP client] -->|stdio| B[9Router MCP]
B -->|HTTP or HTTPS| C[Your 9Router instance]
C --> D[Configured providers]Installation
Requires Node.js 22 or later and a running 9Router. Connect the providers you want to use in the 9Router dashboard.
Install with your agent
Once the GitHub repository is public, paste this prompt into your coding agent from any workspace. The agent will clone the repository, build the server, and configure your current harness.
Install the unofficial 9Router MCP server into my current agent harness.
Clone https://github.com/lucian-voss/9router-mcp into a persistent folder
outside my current project. If there is already a checkout for that GitHub
repository, reuse it and preserve any local changes. If GitHub is
unreachable or the repository isn't accessible, report the error before
changing any harness settings.
In the checkout, check for Node.js 22 or newer, then run npm ci and
npm run build. Use the matching host example in its README.md to configure
a stdio server named ninerouter using node and the absolute path to the
checkout's dist/cli.js. Preserve my existing MCP servers and settings.
If you can't identify the harness or which config to edit, ask me.
Use http://localhost:20128 unless I specify a different 9Router URL. If my
gateway requires NINEROUTER_KEY, use an existing environment variable or
the host's secret store. Keep its value out of chat and shared config.
Verify the host can discover ninerouter_health and call it if available.
Report where you installed it, which config you changed, and any checks
you couldn't complete.Update with your agent
Paste this prompt into your coding agent from any workspace to update an existing source installation to the latest published main commit.
Update the unofficial 9Router MCP server used by my current agent harness.
Find the ninerouter entry in the harness configuration and use the path to
dist/cli.js to locate the installed checkout. Verify its origin is
https://github.com/lucian-voss/9router-mcp. If you can't identify the
installation or it uses a different source, ask me before changing anything.
Record the current commit and fetch origin. If the checkout has local edits,
is off main, or has commits ahead of or diverging from origin/main, report
what you found and ask before proceeding. Otherwise, update main with
git merge --ff-only origin/main. Preserve my harness config and credentials.
With Node.js 22 or newer, run npm ci, npm run build, and
node dist/cli.js --version in that checkout. Reload the MCP server if the
harness supports it, then verify it can discover and call ninerouter_health.
If a restart is required, tell me instead of closing my active session.
Report the previous and current commits and which checks passed.Install manually from source
npm ci
npm run build
node dist/cli.js --versionUse node with the absolute path to dist/cli.js in your MCP host. This checkout also builds an npm tarball with npm pack. After installing that tarball, mcp-9router-gateway is the executable.
npm registry
mcp-9router-gateway is currently unpublished. Once a release is published, the MCP host can launch it with npx -y mcp-9router-gateway@0.1.0, assuming 0.1.0 is the published version. Pinning the version keeps the host on the release you verified.
Related MCP server: @modelbay/mcp
Set up a host
The examples use a local gateway with authentication disabled. For a different gateway, set NINEROUTER_URL in the server environment. For an authenticated gateway, set NINEROUTER_KEY through your host's environment configuration or secret store. Keep keys out of shared configuration files. Replace /absolute/path/to/dist/cli.js with the real path.
Claude Code
claude mcp add --scope user --transport stdio ninerouter -- node /absolute/path/to/dist/cli.js
claude mcp listCodex
[mcp_servers.ninerouter]
command = "node"
args = ["/absolute/path/to/dist/cli.js"]
env_vars = ["NINEROUTER_URL", "NINEROUTER_KEY"]Add this to your Codex config.toml and start Codex with any required variables set.
OpenCode 2.x
{
"mcp": {
"servers": {
"ninerouter": {
"type": "local",
"command": ["node", "/absolute/path/to/dist/cli.js"]
}
}
}
}Add this to opencode.json and run opencode mcp list. OpenCode 1.x uses entries directly under mcp and a different configuration schema.
OpenClaw
openclaw mcp set ninerouter '{"command":"node","args":["/absolute/path/to/dist/cli.js"]}'
openclaw mcp probe ninerouterHermes Agent
mcp_servers:
ninerouter:
command: node
args:
- /absolute/path/to/dist/cli.jsAdd this entry to your Hermes config.yaml and run hermes mcp test ninerouter. See Hermes MCP setup for per-server environment variables and secret handling.
Usage
Start with ninerouter_health and ninerouter_list_models. Pick an ID that matches the operation, then pass it to the tool. For example, call ninerouter_web_search with {"model":"exa/search","query":"Model Context Protocol specification","max_results":5} if your gateway advertises that model. Use ninerouter_model_info for model-specific parameters.
For web tools, the server translates a catalog ID such as exa/search or firecrawl/fetch to the provider alias expected by the gateway.
Capability | Tools, with the |
Discovery |
|
Research |
|
Chat and vision |
|
Media |
|
Embeddings |
|
Video |
|
For binary images and speech, the server emits MCP media content. Image URL mode works for clients that cannot display native images. Transcription accepts base64 input and sends a multipart upload. Omit language when using cx/transcribe. Video submission returns a job object. Pass that object to video_status to poll on the originating provider connection. Upstream SSE and Ollama JSON lines are collected into a bounded result.
Configuration
Environment variable | Default | Purpose |
|
| Gateway base URL, optionally ending in |
| unset | Gateway bearer key when authentication is enabled. |
|
| Request deadline, including response body reads. Set the host's tool timeout accordingly. |
|
| Maximum upstream request or response body size. MCP serialization and media base64 can increase the final message size. |
|
| In-flight requests per server process. |
| all tools | Comma-separated allowlist of full tool names. |
See compatibility and known limits and security.
Development
npm run typecheck
npm test
npm pack --dry-runThe integration tests launch the compiled server and use a local mock gateway. They require no provider accounts or paid requests.
Available Tools
17 toolsninerouter_chatB
Run a 9Router chat or vision model. Select the API dialect and supply its native request fields.
Inputs: model (required), request (required), stream, dialect.
ninerouter_compact_responseC
Compact an OpenAI Responses conversation through 9Router.
Inputs: model (required), request (required).
ninerouter_count_tokensCRead-onlyIdempotent
Count tokens for an Anthropic Messages request using 9Router.
Inputs: model (required), request (required).
ninerouter_edit_videoC
Submit an edit job using a source video.
Inputs: request (required), model.
ninerouter_embedC
Create embeddings for text, text batches, or supported token inputs.
Inputs: input (required), model (required), options, dimensions, +1 more.
ninerouter_extend_videoC
Submit an extension job using a source video.
Inputs: request (required), model.
ninerouter_generate_imageC
Generate or edit an image using the selected 9Router model.
Inputs: model (required), prompt (required), n, size, +4 more.
ninerouter_generate_videoC
Submit a video generation job using a prompt or source image.
Inputs: request (required), model.
ninerouter_healthARead-onlyIdempotent
Check whether the configured 9Router instance is healthy.
Inputs: no named parameters.
ninerouter_list_modelsCRead-onlyIdempotent
List chat models, fallback combos, or models for a specific capability.
Inputs: kind.
ninerouter_list_voicesBRead-onlyIdempotent
List text-to-speech voices for a provider and optional language.
Inputs: provider (required), lang.
ninerouter_model_infoCRead-onlyIdempotent
Inspect the parameters and capabilities advertised for a model.
Inputs: id (required).
ninerouter_text_to_speechC
Convert text to speech using a configured 9Router voice.
Inputs: input (required), model (required), voice, options, +1 more.
ninerouter_transcribe_audioC
Transcribe inline base64 audio through 9Router using a multipart upload.
Inputs: model (required), file_base64 (required), prompt, options, +4 more.
ninerouter_video_statusCRead-onlyIdempotent
Poll a video job with the job reference returned at submission.
Inputs: job (required).
ninerouter_web_fetchB
Extract a public web page as Markdown, text, or HTML through 9Router.
Inputs: url (required), model, format, options, +3 more.
ninerouter_web_searchC
Search public web, news, or X using a configured 9Router search provider.
Inputs: query (required), model, country, options, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target clearly distinct operations across chat, embeddings, media, search, and utility tasks. The closest overlap is between list_models and model_info, and among the video job tools, but their descriptions provide enough separation to select correctly.
All tools share a consistent ninerouter_ prefix and snake_case naming. Most names use an action-oriented verb_noun pattern, with a few noun-based read/status names such as health, model_info, and video_status as minor deviations.
Seventeen tools is somewhat heavy but justified by the broad multi-modal gateway scope: chat, models, embeddings, images, video, speech, transcription, web access, and token utilities. Each tool maps to a meaningful capability rather than duplicating another.
The surface covers the main AI gateway workflows well, including model discovery, chat, embeddings, media generation, speech, transcription, web search/fetch, and health checks. Minor gaps exist around lifecycle operations such as canceling or listing video jobs and possible provider/model management, but agents can work around these.
Maintenance
Related MCP Connectors
An MCP gateway for teams deploying AI tools at scale to employee-facing and headless agents.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
MCP gateway: one connection for your AI apps, with tool policies, PII redaction and audit logs.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible clients to generate images and videos, synthesize speech, clone and design voices, and dynamically configure API interactions.468 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to use chat, image generation and editing, video, speech, music, voice cloning and design, and transcription across Volcengine Ark, Alibaba Bailian, MiniMax, Doubao Speech, and OpenAI.MIT
- AlicenseNot gradedqualityBmaintenanceConnects AI agents and MCP clients to a hosted gateway for authenticated tool discovery and governed execution, including inspecting campaigns and creating empty campaigns for manual configuration.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to use a self-hosted gateway for image and video generation, short-drama storyboard editing, asset/resource lookup, and canvas project management through scoped tools.MIT