MCP server

melange mcp serves the same Melange operations as MCP tools instead of shelling out. 18 tools over stdio (17 over Streamable HTTP — upload_model needs the caller's local files) so MCP clients call Melange directly.

The stdio server reuses the CLI's credentials (MELANGE_API_KEY or melange auth login), resolved lazily on the first tool call. The HTTP server is credential-less: every request must carry its own Authorization: Bearer <token>, so one deployment serves many callers.

Install the CLI first so melange is on your PATH, then register it with your client. The full tool catalog and per-transport details are in llms.txt.

Transports

upload_model is stdio-only because the server cannot see the caller's filesystem. request_model_download never writes files — it only authorizes.

Claude Code

claude mcp add melange -- melange mcp

Verify with claude mcp list — the entry should show ✔ Connected.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config; macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "melange": {
      "command": "melange",
      "args": ["mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "melange": {
      "command": "melange",
      "args": ["mcp"]
    }
  }
}

Remote (Streamable HTTP)

For remote agent clients, serve the Streamable HTTP transport. The server itself holds no credentials: every request must carry its own token as Authorization: Bearer <token>, so one deployment serves many callers.

The server speaks plain HTTP; terminate TLS in front of it (load balancer, reverse proxy, or ingress). The https:// client URLs below assume that.

melange mcp --transport http --listen 0.0.0.0:8080

Claude Code:

claude mcp add --transport http melange https://your-host:8080/ \
  --header "Authorization: Bearer ztp_your_personal_access_token"

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "melange": {
      "url": "https://your-host:8080/",
      "headers": {
        "Authorization": "Bearer ztp_your_personal_access_token"
      }
    }
  }
}

Claude Desktop registers local stdio servers through claude_desktop_config.json (above); remote servers are added as custom connectors in claude.ai settings instead. See melange mcp --help for HTTP flags.

HTTP flags

GET /healthz is an unauthenticated liveness probe. /.well-known/oauth-protected-resource is public discovery. Every other path requires Authorization: Bearer <token>; missing token is 401 Bearer, wrong audience/scope is 403 insufficient_scope (OAuth) or an in-band tool error (PAT passthrough).

Tool catalog

The catalog is typed and versioned with the OpenAPI spec. Every tool declares readOnlyHint, destructiveHint, idempotentHint, openWorldHint explicitly, and every outputSchema is type: object. Byte-exact JSON passthrough preserves API response order and characters (<, & survive).

Stdio 18 vs HTTP 17 is pinned by internal/mcp/testdata/tools_list_*.json goldens; a new mutating tool cannot ship without joining the write scope.

When to use CLI vs MCP

• Prefer MCP when the server is connected: typed arguments, no shell, confirm gates.
• Use CLI when there is no tool: melange auth login/status/token/logout, melange model download to disk, bucketed .pt2 or --input-manifest uploads, melange api raw, or when over HTTP you need local files (upload_model).

All agent rules (non-blocking conversion monitoring, pipeline panel, report templates) apply unchanged whether data came from CLI or MCP — see the ## melange mcp section of llms.txt and the skills/melange-cli/SKILL.md skill.

Exit codes

0 clean disconnect (stdio) or completed drain after SIGINT/SIGTERM (http), 1 serve failure, 2 usage, 130 interrupted (or http drain cut short by second signal). STDOUT carries JSON-RPC frames only; diagnostics go to STDERR.

Registry

server.json (ai.zetic/melange, 0.5.0) is the MCP registry entry (stdio via npx @zetic-ai/melange-cli). npm/package.json carries mcpName.