Skip to main content
Glama
Brooks-Sem

Brooks Model MCP

by Brooks-Sem
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Brooks Model MCP

统一的 Codex、Claude 与 Grok 直接会话 MCP 服务，面向 VS Code、Claude Code 及其他支持 stdio MCP 的客户端。

设计

三个入口相互隔离：

  • mcp-codex：调用本机 Codex CLI，复用 ~/.codex 中的认证、模型与思考强度；默认启用原生实时网页搜索。

  • mcp-claude：调用本机 Claude Code CLI，复用 ~/.claude 中的认证与模型；暴露按次思考强度并默认允许 WebSearch/WebFetch。

  • mcp-grok：调用 OpenAI 兼容的 Grok API；默认模型与思考强度由 server 环境配置，默认通过 Responses API 使用 web_search。

Codex 和 Claude 使用上游 CLI 的原生 session/thread。Grok API 通常无服务端会话，本项目使用本机 SQLite 保存消息历史并提供可续接 session。

Related MCP server: CLI Agent MCP

对话、长文本与权限

  • 三个首轮工具都返回 sessionId，后续分别传给 codex_reply、claude_reply、grok_reply 即可连续对话。

  • Codex/Claude 的输入通过 stdin 传给 CLI，Grok 通过 HTTP JSON 发送；代码不按字符数静默截断输入。

  • Codex 使用原生 JSONL 事件流，Claude 使用 stream-json；server 会消费实时事件并通过 MCP progress notification 发送节流后的状态摘要。状态摘要不包含 prompt、模型正文或命令输出。

  • 最终响应仍是一次完整的结构化 MCP 结果，不是多次 token 结果。客户端只有在调用时提供 progress token 且实现了相应 UI 时才会展示中间状态；超长输出仍宜分轮索取，需要产出大型文档时，只在明确授权写入后交给 Codex 保存到工作区。

  • Codex/Claude 的上下文管理由各自 CLI 负责。Grok 将本地 SQLite 中的完整消息历史随续聊请求重发，达到模型上下文上限后应开启新 session 或先请求压缩摘要。

  • 默认权限是只读：Codex 默认 sandbox=read-only，Claude 固定 permission-mode=plan 且只开放读取和网页工具，Grok 不开放本地文件工具。

  • 只有 Codex 可在单次调用中显式指定 sandbox=workspace-write。不建议让多个外部模型并发修改同一工作区；更稳妥的模式是三者研究/审查，主代理统一落盘。

  • 三者的 web_search 参数默认均为 true，可按调用设为 false。搜索能力仍受上游账号、组织策略及兼容 API endpoint 支持情况约束。

超时与取消

  • Codex/Claude 没有总运行时限，只受“连续无任何输出”的空闲时限约束，默认 300 秒。只要 stdout 或 stderr 仍间歇产生数据，调用就可以无限运行。

  • 通过 MODEL_MCP_CLI_IDLE_TIMEOUT_SECONDS 调整空闲阈值；值必须为正数。旧的 MODEL_MCP_CLI_TIMEOUT_SECONDS 不再读取，也不会形成隐藏的 900 秒上限。

  • 达到连续静默阈值或 MCP 调用被取消时，server 会终止当前上游进程并清理管道；Windows 使用 Job Object 回收整个子进程树。

  • Grok 使用 GROK_TIMEOUT_SECONDS 控制 HTTP connect/read/write/pool 超时，默认 180 秒。无响应超时不会自动重试；明确的临时 HTTP 状态或连接失败仍受 GROK_MAX_RETRIES 约束。

  • 超时只关闭当前无响应调用，不关闭 MCP server。后续仍可发起新 session；超时 turn 不应继续复用，避免上游历史处于不确定状态。

  • MCP progress 是可选通知，不保证覆盖宿主客户端自身设置的固定工具调用硬超时。如果宿主仍在某个固定时长中止调用，需要同时调整宿主的 MCP/tool timeout 配置。

安全边界

  • API key、token、SQLite session、日志和本地配置不会进入 Git。

  • prompt 通过 stdin 传给 Codex/Claude，不拼接 shell 命令。

  • Codex/Claude 默认只读。

  • Grok key 只从 server 进程环境读取，不接受 MCP 工具参数传入，也不会在诊断结果中回显。

Conda 环境

Conda 仅用于开发、测试和发布前验收，不进入 MCP 客户端启动链：

conda env create -f environment.yml
conda activate mcpserver
pytest
ruff check .

已有环境可更新：

conda activate mcpserver
python -m pip install -e ".[dev]"

MCP 配置

客户端配置严格使用 uvx --from git+https://...，与 Claude Code 中现有 Git MCP 的配置方式一致。生产配置必须锁定 tag 或 commit：

{
  "servers": {
    "codex": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0",
        "mcp-codex"
      ]
    },
    "claude": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0",
        "mcp-claude"
      ]
    },
    "grok": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0",
        "mcp-grok"
      ],
      "env": {
        "GROK_API_URL": "${input:grok-api-url}",
        "GROK_API_KEY": "${input:grok-api-key}",
        "GROK_MODEL": "grok-4",
        "GROK_REASONING_EFFORT": "high"
      }
    }
  }
}

完整模板位于 configs/。新机器只需安装 Git、uv、Codex CLI 和 Claude Code CLI；uvx 会从 Git tag 创建并缓存隔离环境。

不要在长期配置中省略 @v0.1.0。直接跟随 main 会让未经本机验收的更新自动进入三个 MCP server。

Grok 配置

Grok 没有被本项目依赖的本地 CLI 会话层。server 从进程环境读取：

环境变量

说明

默认值

GROK_API_URL

OpenAI 兼容 API base URL

必填

GROK_API_KEY

API key，只允许本机配置

必填

GROK_MODEL

server 默认模型

grok-4

GROK_REASONING_EFFORT

默认思考强度：low/medium/high/xhigh/max

high

GROK_REASONING_FIELD

兼容 endpoint 的请求字段；空值表示不发送

reasoning_effort

GROK_TIMEOUT_SECONDS

请求超时

180

GROK_MAX_RETRIES

可重试请求次数

3

grok / grok_reply 工具允许按次覆盖 model 与 reasoning_effort，但不接受 key 或 API URL 参数。Grok session 存储于本机 SQLite，不上传 Git。

验证

.\scripts\doctor.ps1
conda run -n mcpserver pytest
conda run -n mcpserver ruff check .

发布后验证远程 tag：

uvx --from "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0" mcp-doctor

Available Tools

2 tools
codexB

Start a direct Codex CLI conversation and return a resumable thread ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
modelNo
promptYes
sandboxNoread-only
web_searchNo
reasoning_effortNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
modelNo
resultYes
metadataNo
sessionIdYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral burden. It usefully reveals that a thread ID is returned and that the conversation is resumable, but it says nothing about side effects, code execution, sandbox behavior, authentication, or failure modes. 'Direct CLI conversation' is too vague to understand what actually happens.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. It states the action and the most important result immediately, so every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description leaves major gaps: it does not explain sandbox modes, what a 'direct conversation' means for execution, how to choose model or reasoning_effort, or how the returned thread ID should be used with codex_reply. For a tool with six parameters and a sibling, this is not enough context for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description names none of the six parameters. The schema only supplies field names, defaults, and an enum; without explanation, an agent cannot know the meaning of cwd, sandbox, web_search, or reasoning_effort. The description does nothing to compensate for this gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Start') with a clear resource ('Codex CLI conversation') and states the key result ('return a resumable thread ID'). This makes the tool's purpose unambiguous and distinguishes it from the sibling tool codex_reply, which presumably continues an existing conversation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this tool is for initiating a conversation, especially by emphasizing the resumable thread ID. It does not explicitly mention when not to use it or name codex_reply as the alternative, but the context is clear enough for an agent to route initial calls here.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_replyB

Continue a Codex CLI conversation using a prior thread ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
modelNo
promptYes
session_idYes
web_searchNo
reasoning_effortNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
modelNo
resultYes
metadataNo
sessionIdYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavior disclosure. It only states that the tool continues a conversation; it does not mention that Codex might execute commands, modify files, or take side-effecting actions, nor does it describe what happens after the reply is produced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It is concise, though it borders on under-specification rather than being a model of efficient completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With six parameters, no annotations, and a sibling tool, one sentence is not enough. The agent is not told when to choose 'codex_reply' over 'codex', what the prompt should contain, or how optional parameters affect behavior. The output schema does not compensate for these invocation-level gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only clarifies that 'session_id' refers to a prior thread ID. Required and optional parameters like 'prompt', 'cwd', 'model', 'web_search', and 'reasoning_effort' are left completely unexplained by the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Continue') and a clear resource ('a Codex CLI conversation') while adding the key mechanism ('using a prior thread ID'). This distinguishes it from the sibling 'codex' tool, which presumably starts a new conversation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'using a prior thread ID' gives a clear contextual signal for when this tool is appropriate: when there is an existing Codex session to continue. However, it does not explicitly state when not to use it or name the alternative 'codex' for starting new conversations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observedcodex
    • First observedcodex_reply
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: codex starts a new conversation and returns a thread ID, while codex_reply continues an existing conversation using that ID. There is no overlap or ambiguity between them.

Naming Consistency4/5

Both tools use lowercase snake_case and share the 'codex' prefix, making them predictable. However, one is a bare noun and the other is a noun-reply compound, so the naming pattern is not strictly verb_noun, though it remains consistent in style.

Tool Count3/5

With only two tools, the server sits at the thin end of the scale. For a focused Codex conversation interface, start and reply are the core operations, so the count is reasonable for the narrow purpose, but it feels minimal.

Completeness4/5

The core conversation lifecycle—initiate and continue—is fully covered, which is the primary use case. Missing capabilities like listing or ending threads are minor gaps that agents can work around.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • CLI Agent MCP

    shiharuharu
    A
    license
    A
    quality
    F
    maintenance
    Provides unified access to multiple CLI AI agents (Codex, Gemini, Claude, and OpenCode) through a single MCP interface with real-time task monitoring, enabling specialized code analysis, UI design, implementation, and prototyping workflows.
    11
    21
    MIT

  • Vox MCP

    linxule
    A
    license
    A
    quality
    A
    maintenance
    Enables MCP clients like Claude Code and Cursor to use multiple AI models (Gemini, GPT, Grok, DeepSeek, Kimi, Ollama) via a unified chat tool with conversation memory.
    3
    76 PyPI
    1
    Apache 2.0

  • all-agents-mcp

    Dokkabei97
    A
    license
    B
    quality
    F
    maintenance
    Enables orchestrating multiple AI CLI agents (Claude Code, Codex, Gemini CLI, Copilot CLI) through a unified MCP interface for task delegation, cross-agent comparison, and specialized tools like code review and debugging.
    14
    17 npm
    14
    MIT