Blaze MCP Server

A production-ready MCP server that connects any MCP client (Antigravity, Claude Desktop, Cursor, VS Code, ...) to the BlazeAPI OpenAI-compatible endpoint.

Built with the official @modelcontextprotocol/sdk, TypeScript, axios, and zod.

Features

• chat — send a prompt and get only the generated text.
• Focus files — add files to a "focused" set with focus_file; their contents are injected into every subsequent chat request so Blaze prioritises that code without needing an explicit read_file.
• Memory — pass a conversation_id to continue a conversation; history is persisted to disk (.blaze-memory.json) so Blaze remembers previous messages even across server restarts.
• switch_model — change the active model at runtime (persisted to .blaze-state.json), no .env edits needed.
• server_info — version, API URL, active model, connectivity ping, tool list.
• Developer tools — explain_code, review_code, fix_bug, optimize_code, generate_tests, explain_error, generate_commit_message.
• File tools — read_file, summarize_file, explain_file, review_file, translate_markdown.
• list_models — models fetched from /models, not hardcoded.
• Streaming — streamChat() yields token deltas; optional HTTP/SSE mode (serverUrl) for clients that stream responses.
• Resilience — retry with exponential backoff + jitter for timeout/429/5xx; configurable timeout; error normalization (401/403/404/429/5xx/timeout/ network/JSON) mapped to friendly MCP isError responses. Never crashes.
• Logging to stderr only so the stdio protocol on stdout is never corrupted.

Requirements

• Node.js >= 20
• A BlazeAPI key (from https://blazeapi.org)

Setup

npm install
npm run build

Configure .env:

BLAZE_API_KEY=blaze-xxxx
BLAZE_MODEL=deepseek-v4-pro

Optional settings (with defaults):

BLAZE_BASE_URL=https://api.blazeapi.org/paid/v1
BLAZE_TIMEOUT_MS=90000
BLAZE_MAX_RETRIES=2
BLAZE_RETRY_BASE_DELAY_MS=1000
BLAZE_HTTP_PORT=3001   # only used in HTTP mode

MODEL is accepted as an alias of BLAZE_MODEL.

Run

npm run dev          # stdio (development)
npm run build        # compile to dist/
npm start            # stdio (production)
npm run dev:http     # HTTP/SSE (development)
npm run start:http   # HTTP/SSE (production)

Stdio

Point your client at:

node D:\blaze-mcp\dist\index.js

HTTP/SSE (streaming)

npm run start:http

Exposes http://localhost:3001/mcp. Clients that support serverUrl (e.g. Antigravity remote mode) connect there and receive streamed responses. Health check: http://localhost:3001/health.

Test with MCP Inspector (browser)

npx @modelcontextprotocol/inspector node dist/index.js

Open http://localhost:6274.

Antigravity setup

Antigravity reads mcp_config.json. The server is already registered globally at ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "blaze-mcp": {
      "command": "node",
      "args": ["D:\\blaze-mcp\\dist\\index.js"]
    }
  }
}

For streaming over HTTP instead, use serverUrl:

{
  "mcpServers": {
    "blaze-mcp": {
      "serverUrl": "http://localhost:3001/mcp"
    }
  }
}

Usage examples

Chat with memory

chat { prompt: "My secret word is PINEAPPLE." }
-> "Got it!"  (note the conversation_id)

chat { prompt: "What is my secret word?", conversation_id: "conv_..." }
-> "PINEAPPLE"

Switch model

switch_model { model: "glm-5.2" }
switch_model { model: "deepseek-v4-pro" }

Focus files

focus_file           { file_path: "src/services/blaze.ts" }
list_focused_files
unfocus_file         { file_path: "src/services/blaze.ts" }

Focused files are injected into the context of every chat call:

focus_file   { file_path: "src/utils/retry.ts" }
chat         { prompt: "what backoff does the focused file use?" }
-> "exponential backoff with a max retry count"

Server info

server_info

Code tools

explain_code    { code: "..." }
review_code     { code: "...", language: "typescript" }
fix_bug         { code: "...", symptom: "throws TypeError" }
optimize_code   { code: "..." }
generate_tests  { code: "...", framework: "vitest" }
explain_error   { error: "..." }
generate_commit_message { diff: "..." }

File tools

summarize_file   { file_path: "README.md" }
explain_file     { file_path: "src/index.ts" }
review_file      { file_path: "src/services/blaze.ts" }
translate_markdown { file_path: "README.md", target_language: "Arabic" }

Architecture

src/
  index.ts             stdio entry point
  http.ts              HTTP/SSE entry point
  config.ts            zod-validated environment config
  server.ts            MCP server instance + tool registry
  tools/
    chat.ts            chat with memory
    models.ts          list_models
    switch_model.ts    runtime model switching
    server_info.ts     server status
    memory.ts          start/clear/list conversations
    code.ts            developer tools
    files.ts           file tools
    focus.ts           focus_file/unfocus_file/list_focused_files
    hello.ts           hello
  services/
    blaze.ts           BlazeApi (chat, streamChat, listModels, resolveModel)
    memory.ts          conversation store (disk-persisted)
    model.ts           active model manager (disk-persisted)
    focus.ts           focused files manager (disk-persisted)
  utils/
    logger.ts          stderr-only logger
    retry.ts           withRetry (backoff + jitter)
    errors.ts          classifyError -> BlazeError
    file.ts            safe file reading
    register.ts        tool registration + registry
  types.ts             BlazeError + error kinds

Scripts

| Command | Purpose | | ------------------- | ------------------------------ | | npm run dev | stdio server (tsx) | | npm run dev:http | HTTP/SSE server (tsx) | | npm run build | compile to dist/ | | npm start | run stdio server | | npm run start:http| run HTTP/SSE server | | npm run typecheck | type-check without emitting | | npm run test | run vitest unit tests |

Tests

Unit tests cover classifyError (error normalization), withRetry (backoff), MemoryService (disk persistence, trimming, corrupted files) and BlazeApi (response parsing, caching, error handling) with a mocked axios client:

npm test

Publish (npm)

When ready to share:

npm login
npm publish

Then anyone can use it globally:

npm install -g blaze-mcp

License

ISC