Skip to main content
Glama

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 --version

Use 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 list

Codex

[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 ninerouter

Hermes Agent

mcp_servers:
  ninerouter:
    command: node
    args:
      - /absolute/path/to/dist/cli.js

Add 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 ninerouter_ prefix

Discovery

health, list_models, model_info, list_voices

Research

web_search, web_fetch

Chat and vision

chat, count_tokens, compact_response

Media

generate_image, text_to_speech, transcribe_audio

Embeddings

embed

Video

generate_video, edit_video, extend_video, video_status

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

NINEROUTER_URL

http://localhost:20128

Gateway base URL, optionally ending in /v1. A reverse-proxy prefix is preserved.

NINEROUTER_KEY

unset

Gateway bearer key when authentication is enabled.

NINEROUTER_TIMEOUT_MS

120000

Request deadline, including response body reads. Set the host's tool timeout accordingly.

NINEROUTER_MAX_BYTES

8388608

Maximum upstream request or response body size. MCP serialization and media base64 can increase the final message size.

NINEROUTER_MAX_CONCURRENT

4

In-flight requests per server process.

NINEROUTER_TOOLS

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-run

The integration tests launch the compiled server and use a local mock gateway. They require no provider accounts or paid requests.

Available Tools

17 tools
ninerouter_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_tokensC
Read-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_healthA
Read-onlyIdempotent

Check whether the configured 9Router instance is healthy.

Inputs: no named parameters.

ninerouter_list_modelsC
Read-onlyIdempotent

List chat models, fallback combos, or models for a specific capability.

Inputs: kind.

ninerouter_list_voicesB
Read-onlyIdempotent

List text-to-speech voices for a provider and optional language.

Inputs: provider (required), lang.

ninerouter_model_infoC
Read-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_statusC
Read-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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers