# Reported issues for grok-mcp

Pod holds 15 of 15 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [grok-mcp](/mcp/grok-mcp).

## Most discussed

### Tool schemas rejected by Claude API: target: "openApi3" emits boolean exclusiveMinimum, invalid under JSON Schema draft 2020-12

## Summary

The server advertises tool input schemas that fail the Claude API's JSON Schema draft 2020-12 validation. Any Claude Code session with the four grok tools loaded gets hard `400`s on **every** API request:

```
API Error: 400 tools.N.custom.input_schema: JSON schema is invalid. It must
match JSON Schema draft 2020-12 (https://json-schema.org/draft/2020-12).
```

Because the API rejects the whole request when any single tool schema is invalid, this breaks entire turns in the host agent

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/32) · 2026-08-03 · open · external user · 0 comments

### Audit and focus the tool surface — double down on review/validation value

## Why this creates value

The project offers four tools:
- grok_review (core value)
- grok_challenge (core value when focused)
- grok_consult
- grok_chat

`grok_chat` is the least differentiated (many other Grok MCPs do general chat better or with more features). Spreading effort across general chat dilutes the unique positioning around **review and second opinion**.

Focusing makes the project:
- Easier to explain in one sentence
- Stronger in its chosen niche
- Less likely to be compared unfa

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/28) · 2026-06-23 · open · 0 comments

### Create raw, high-signal demo assets and usage examples (optimized for developer sharing)

## Why this creates value

What tends to get attention and trust for Grok/xAI related tools (from observed patterns):

- Raw terminal output
- Concrete before/after
- Low-polish, high-signal demos (not fancy websites)
- Clear demonstration that Grok adds something the primary workflow didn't have

Currently the project lacks ready-to-share assets that a developer would actually screenshot or link.

## Deliverables

- A small set of **raw terminal / command examples** showing the four tools in re

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/27) · 2026-06-23 · open · 0 comments

### Professionalize tool descriptions, internal prompts, and example outputs

## Why this creates value

Tone and professionalism matter for perceived quality:

- Prompts currently use language like "hostile senior engineer", "be specific and ruthless", "break this code".
- This leaks into outputs and makes the tool feel more like a stunt than infrastructure.
- Tool descriptions in the MCP server and README should clearly communicate the *value* ("second opinion", "catch issues your primary model is likely to miss", "detailed structured feedback").

Cleaning this up incre

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/26) · 2026-06-23 · open · 0 comments

### Make the composite GitHub Action (grok-review) zero-friction and truly production-ready

## Why this creates value

The GitHub Action + `grok-review-ci` is currently one of the strongest concrete differentiators (structured review + sticky comment + gating).

However, to create real user value it needs to be **obviously usable by strangers** with minimal setup.

Current friction points:
- Requires secrets + install steps that are not copy-paste simple
- Docs are split between README and the action.yml
- No "quick start for any repo" one-file example that just works
- People may give

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/25) · 2026-06-23 · open · 0 comments

### Reposition core messaging: from 'adversarial challenger / attacker' to 'multi-model second opinion validator'

## Why this creates value

Current positioning ("Grok as the one that attacks Claude's work", "hostile senior engineer", heavy emphasis on grok_challenge as adversarial) creates several problems:

- Risks alienating the primary audience that actually installs MCP servers (heavy Claude Code / Cursor / Cline users).
- Reads as tribal "Grok vs Claude" warfare rather than a useful engineering tool.
- Independent reviews (including 3rd-party analysis) flag this framing as a major optics and adoption 

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/23) · 2026-06-23 · open · 0 comments

### Support --rules flag (auto-pipe CLAUDE.md / project rules)

## Goal
Let Grok respect project-specific lint rules and conventions during \`grok_review\` / \`grok_challenge\` without callers manually prepending them.

## Background
Grok CLI supports \`--rules <RULES>\` — extra text appended to the system prompt. A natural source for those rules is the calling project's \`CLAUDE.md\` (or \`AGENTS.md\` / \`.cursorrules\` / \`GEMINI.md\`).

## Proposal
Add to \`grok_review\` / \`grok_challenge\`:

\`\`\`ts
rules?: string                     // explicit rules

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/12) · 2026-05-26 · open · 0 comments

### Add grok_models tool (list available models)

## Goal
Let callers programmatically discover which Grok models the user's CLI has access to, so \`model\` params can be validated / auto-completed.

## Proposal
New tool \`grok_models\`:

\`\`\`ts
{
  name: "grok_models",
  inputSchema: z.object({}),  // no args
  handler: async () => {
    // run \`grok models\`, parse output, return JSON list
  }
}
\`\`\`

Output shape (string-wrapped JSON):
\`\`\`json
{
  "default": "grok-build",
  "available": ["grok-build", "grok-4", ...]
}
\`\`\`

Cache r

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/11) · 2026-05-26 · open · 0 comments

## Most recent

### Expose MCP resources endpoint (help / models / prompt examples)

## Goal
Let MCP-aware hosts discover ambient context about grok-build-mcp without round-tripping a tool call.

## Background
MCP defines a \`resources\` capability separate from \`tools\` — read-only data the server exposes (file URIs, doc snippets, schemas). Top MCP servers (MongoDB, AWS) ship resources alongside tools.

## Proposal
Implement \`resources/list\` and \`resources/read\` to expose:

- \`grok://help\` — output of \`grok --help\`
- \`grok://models\` — output of \`grok models\`
- \`gr

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/10) · 2026-05-26 · open · 0 comments

### MCP streaming response via progress notifications

## Goal
Stream Grok's reasoning/output incrementally so the calling agent sees progress on long reviews instead of a 30-second blank.

## Background
- Today \`runGrok\` buffers the entire stdout and returns once on close.
- MCP supports \`notifications/progress\` for long-running tools.
- Grok CLI supports \`--output-format streaming-json\` for incremental NDJSON output.

## Proposal
- Add \`stream: true\` option to \`grok_chat\` / \`grok_review\` / \`grok_consult\` / \`grok_challenge\`.
- When 

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/9) · 2026-05-26 · open · 0 comments

### Add README badges (npm version, downloads, CI status, MIT)

## Goal
Standard at-a-glance signals at the top of the README.

## Proposal
Right under the title, add:

\`\`\`md
[![npm version](https://img.shields.io/npm/v/grok-build-mcp.svg)](https://www.npmjs.com/package/grok-build-mcp)
[![npm downloads](https://img.shields.io/npm/dm/grok-build-mcp.svg)](https://www.npmjs.com/package/grok-build-mcp)
[![CI](https://github.com/howardpen9/grok-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/howardpen9/grok-mcp/actions/workflows/ci.yml)
[![License:

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/8) · 2026-05-26 · open · 0 comments

### Add CONTRIBUTING.md + GitHub issue templates

## Goal
Lower friction for outside contributors so triage stays easy.

## Proposal
1. `CONTRIBUTING.md` covering:
   - How to run tests (`npm test`) and build (`npm run build`)
   - Branch / commit message conventions
   - PR checklist (tests pass, README updated if behaviour changes, no debug logging left in)
2. `.github/ISSUE_TEMPLATE/bug_report.yml` — reproduction steps, expected vs actual, MCP host, grok CLI version
3. `.github/ISSUE_TEMPLATE/feature_request.yml` — problem, proposed tool/sch

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/5) · 2026-05-26 · closed · 0 comments

### Expose reasoning_effort / best_of_n / check flags

## Goal
Expose Grok CLI's three highest-leverage quality flags so callers can trade latency for review depth.

## Background
Grok CLI supports:
- `--reasoning-effort <low|medium|high|xhigh|max>` — controls reasoning budget.
- `--best-of-n <N>` — runs N parallel attempts and returns the best (huge for code review).
- `--check` — appends a self-verification loop to the prompt.

None are surfaced by the MCP wrapper today.

## Proposal
Add the following to all four tools' input schemas:

\`\`\`ts
re

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/3) · 2026-05-26 · open · 0 comments

### Add output_format: "json" option for grok_review and grok_challenge

## Goal
Let programmatic consumers (CI bots, IDE integrations) parse structured verdicts/scores instead of regex-grepping markdown.

## Background
Grok CLI supports `--output-format plain | json | streaming-json`. Today both `grok_review` and `grok_challenge` always return markdown text.

## Proposal
Add `output_format` to both tools' input schema:

\`\`\`ts
output_format?: "markdown" | "json"  // default "markdown"
\`\`\`

When `json`:
- Pass `--output-format json` through to grok CLI.
- For `g

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/2) · 2026-05-26 · open · 0 comments

### Add session persistence to grok_consult

## Goal
Eliminate per-call overhead of re-passing the full message history for multi-turn Grok conversations.

## Background
Grok CLI natively supports `-c/--continue` (resume most recent session) and `-r/--resume <SESSION_ID>`. Currently `grok_consult` is fully stateless — the caller passes the full `messages[]` every call. For long reviews / iterative debugging this becomes wasteful and lossy.

## Proposal
Add optional `session_id` parameter to `grok_consult`:

- When `session_id` is absent → 

[Read the thread](https://github.com/howardpen9/grok-mcp/issues/1) · 2026-05-26 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/howardpen9/grok-mcp/issues).