Skip to main content
Glama
Sign In
Codex OpenRouter MCP

Codex OpenRouter MCP

by bladehstream
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Codex OpenRouter MCP

Unofficial public alpha. This project is not affiliated with or endorsed by OpenAI, OpenRouter, DeepSeek, Z.ai, or any listed inference provider. It is not submitted to the universal Codex plugin directory. Review the security policy and outstanding roadmap before use. The project is source-available under the PolyForm Noncommercial License 1.0.0, not an OSI-approved open-source license. Commercial use requires separate permission.

A local, security-focused STDIO MCP server that lets a Sol or Astra Codex parent delegate bounded work to explicitly approved OpenRouter model/provider routes.

Current profiles:

Profile

Model

Provider order

deepseek_high

deepseek/deepseek-v4.1-flash

Fireworks, Relace, Novita, SiliconFlow

glm_mechanical

~z-ai/glm-flash-latest

Relace, Wafer

Every request enforces Zero Data Retention, denies provider data collection, and prevents routing outside the configured provider list.

Capabilities

  • synchronous delegation;

  • selected-file review for up to 100 UTF-8 source and text files, limited to 500 KB each and 750 KB combined;

  • follow-up-capable asynchronous file review with an in-memory hashed snapshot;

  • compatibility with externally configured OpenRouter workspace/API-key guardrails, with an optional user-supplied local pre-transmission scanner;

  • versioned, weighted model/provider profiles with a validated external JSON override and configuration hash;

  • in-memory asynchronous jobs, status, follow-up, result, and cancellation;

  • selected-file artifact preparation;

  • in-memory artifact preview with SHA-256 manifests;

  • approval-oriented atomic new-file creation under artifacts/openrouter/;

  • Windows Credential Manager, macOS Keychain, and Linux Secret Service support;

  • no runtime Python dependencies.

The artifact boundary does not provide external models with shell access, arbitrary file reads, source-tree writes, or existing-file replacement.

The bundled MCP is optional to Codex session startup. If its executable, configuration, or handshake fails, Codex must still start; only delegator tools are unavailable. Unsafe file roots similarly disable file tools without closing the MCP handshake.

OpenRouter guardrails are not provisioned or verified by this MCP. Without an optional local scanner, selected content reaches OpenRouter before any assigned OpenRouter guardrail evaluates it.

Related MCP server: OpenCode MCP Orchestrator

Install for development

uv sync --python 3.11

Run the server:

uv run codex-openrouter-mcp

See Codex configuration for setup and the security policy for the current trust boundary. See delegation and continuation for synchronous versus asynchronous IDs, file-review follow-ups, reasoning budgets, and finalization. See routing configuration to change models, providers, weights, reasoning policy, or profile instructions without editing Python. See the implementation plan for the dependency-ordered path from the current review/artifact boundary to isolated coding and testing.

For skill-guided installation through the repository's Git marketplace, see plugin installation. The bundled delegate-openrouter skill teaches Codex how to route work, preserve the parent model's coordination role, verify delegate output, and use the approval-gated artifact workflow. If delegation prevents a new Codex task from starting or a Windows upgrade leaves a partial uv environment, follow the troubleshooting runbook.

License

This project is licensed under the PolyForm Noncommercial License 1.0.0, SPDX identifier PolyForm-Noncommercial-1.0.0. It permits use, modification, and distribution for noncommercial purposes defined by that license. It does not grant commercial use. For commercial licensing enquiries, contact the repository owner through the bladehstream GitHub profile.

The canonical license text controls. This summary is provided only for convenience and does not modify the license.

Tests

uv run python -m unittest discover -s tests -p "test_*.py" -v

Paid live tests are intentionally excluded from CI:

uv run python tests/live_acceptance.py

Status

Public alpha. Inline delegation, bounded selected-file review, and inert text artifacts are implemented and tested. Near-native repository exploration, patching, worktrees, and test execution remain separately gated work. See TODO.md for the complete roadmap and directory-readiness criteria.

Available Tools

14 tools
cancel_taskA
Read-only

Request cancellation of a queued or running in-memory delegation.

Inputs: job_id (required).

commit_artifactA

Atomically create validated new artifact files after preview and hash confirmation.

Inputs: job_id (required), expected_manifest_sha256 (required).

delegate_taskA
Read-only

Run one bounded inline-text task synchronously with an approved external model.

Inputs: task (required), profile (required), max_output_tokens.

discard_artifactB
Read-only

Discard an uncommitted in-memory artifact proposal; committed files are untouched.

Inputs: job_id (required).

get_task_resultB
Read-only

Return the completed result and model/provider audit metadata.

Inputs: job_id (required).

get_task_statusB
Read-only

Read status for an asynchronous delegation job.

Inputs: job_id (required).

list_artifact_jobsA
Read-only

List metadata for in-memory artifact proposals without returning their contents.

Inputs: no named parameters.

list_profilesA
Read-only

List approved model/provider profiles, privacy policy, server/plugin versions, and configured-but-unverified guardrail expectation.

Inputs: no named parameters.

prepare_artifactC
Read-only

Read explicitly approved text inputs and stage new validated artifacts in memory.

Inputs: task (required), outputs (required), profile (required), input_paths.

preview_artifactA
Read-only

Preview an in-memory artifact proposal and its content hashes without writing files.

Inputs: job_id (required).

review_filesA
Read-only

Synchronously review 1-100 explicitly named UTF-8 text or source files under the locked workspace root, up to 500 KB each and 750 KB combined. This call cannot be continued with send_followup.

Inputs: task (required), profile (required), input_paths (required), max_output_tokens.

send_followupA
Read-only

Continue a completed in-memory delegation with a bounded follow-up.

Inputs: job_id (required), message (required).

start_file_reviewA
Read-only

Start a follow-up-capable review of 1-100 explicitly named UTF-8 text or source files, retaining the exact hashed input snapshot in memory for send_followup.

Inputs: task (required), profile (required), input_paths (required), max_output_tokens.

start_taskC
Read-only

Start a bounded external-model task and return immediately with a job ID.

Inputs: task (required), profile (required), max_output_tokens.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.3/5.0

    Scored across 14 tools

    Disambiguation3/5

    Tools are mostly separable by domain (profiles, tasks, file reviews, artifacts), but there is ambiguity between synchronous and asynchronous variants (delegate_task vs start_task, review_files vs start_file_review) and send_followup applies to both tasks and file reviews, which could confuse an agent about which context it is for.

    Naming Consistency3/5

    Naming is mostly verb_noun but inconsistent in verb choice: delegate vs start, review_files vs start_file_review, and get_task_result vs get_task_status are similar but not parallel. The start_ prefix is applied unevenly, and send_followup is a generic verb that doesn't match the pattern.

    Tool Count5/5

    14 tools is within the ideal 3-15 range and each tool appears to serve a distinct role in task delegation, file review, and artifact management. No tool seems redundant or unnecessary.

    Completeness3/5

    The surface covers task lifecycle (start, status, result, cancel, follow-up) and artifact lifecycle (prepare, preview, commit, discard, list), but file reviews lack a dedicated cancel mechanism and there is no explicit result retrieval for async file reviews, relying on generic get_task_result or send_followup, which creates potential dead ends.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • OpenCode MCP Orchestrator

      Mesya82
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable coding assistants to delegate repository investigation, bounded implementation work, and noisy command runs (tests, builds, linters) to sandboxed OpenCode agents. Each role can use an independently selected model, and only concise results are returned to the parent agent, which keeps responsibility for architecture and high-risk operations.
      MIT

    • Jev Context MCP

      Smith2912
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables local, bounded routing and evidence judgments for Codex tasks, with tools for reading file context, checking outputs, and selecting registered workflows while keeping execution and review with the client.
      MIT