Medhā MCP

Operator-tuned fork of @veniceai/mcp-server. Same 31 Venice primitives; curated presets for chat/image/video/audio/music baked in via env defaults and surfaced in tool descriptions; one discoverable medha://favorites resource so any agent can fetch the operator's preferences before making a call. Use from any MCP host — Claude Desktop, Claude Code, Cursor, Codex CLI, Hermes, Jiva, Rati, LM Studio, Continue, LibreChat, Open WebUI, AnythingLLM, Jan, Le Chat.

---

What you get

Surface	Count	Notes
Tools	31	Identical to upstream; descriptions augmented with Operator preferences — default: … also try: … overlays keyed off src/presets.ts
Resources	4	venice://models, venice://styles, venice://voices (upstream) + medha://favorites (canonical JSON dump of presets)
Prompts	7	3 upstream (uncensored-research, nsfw-creative-writing, image-style-explorer) + 4 Medhā workflow briefs (medha_music_video_brief, medha_podcast_pipeline, medha_dashboard_poster, medha_character_dossier)
Transports	stdio and Streamable HTTP (/mcp)	HTTP is the Railway-deployed mode; stdio stays for npx-style install

The Medhā MCP server is thin by design: it forwards agent tool calls to api.venice.ai. The agent (Claude Code / Hermes / Codex / Jiva / Rati / Cursor / etc.) is the orchestrator — it plans the steps, picks models, calls tools in order, handles async polling, and stitches art + audio together.

---

Quickstart (5 min deploy on Railway)

1. Get a Venice API key

venice.ai → Settings → API Keys. Save it locally on the operator's Mac:

echo "export VENICE_API_KEY=*** ~/.config/railway/venice-rati-key.env
chmod 600 ~/.config/railway/venice-rati-key.env

2. Clone + push

gh repo clone veniceai/venice-mcp-server ~/tmp/medha-deploy
cd ~/tmp/medha-deploy
# (already customized to Medhā on master if you cloned vivmuk/medha-mcp;
# upstream clone just needs the Phase 1 patches to branding files.)

3. Railway project + service

# Create `medha` project in vivmuk's workspace
railway init --name "medha" --workspace "vivmuk's Projects"
gh repo create vivmuk/medha-mcp \
    --public \
    --description "Medhā — operator-tuned Venice AI MCP bridge." \
    --default-branch master
cd ~/tmp/medha-deploy
git remote rename origin upstream
git remote add origin https://github.com/vivmuk/medha-mcp.git
git fetch upstream --unshallow
git push -u origin master

# Create Railway service that pulls from GitHub
railway add --service medha --repo vivmuk/medha-mcp --branch master

4. Set env vars

Generate a strong bearer token for the MCP HTTP layer:

BEARER=$(python3 -c "import secrets; print(secrets.token_hex(32))")
echo "$BEARER" > ~/.config/railway/medha-bearer.token
chmod 600 ~/.config/railway/medha-bearer.token

Push secrets via --stdin (chat-safe; never argv):

unset RAILWAY_TOKEN RAILWAY_API_TOKEN

python3 - <<'PY'
import subprocess
from pathlib import Path
KEY = Path("/Users/vivgatesai/.config/railway/venice-rati-key.env").read_text()
KV = {l.split("=",1)[0].lstrip("export ").strip(): l.split("=",1)[1].strip().strip('"').strip("'") for l in KEY.splitlines() if l.startswith("export ")}
BEARER = Path("/Users/vivgatesai/.config/railway/medha-bearer.token").read_text().strip()
base = ["railway","variable","set","--service","medha","--skip-deploys"]
for label, value in [("VENICE_API_KEY", KV["VENICE_API_KEY"]), ("VENICE_MCP_AUTH_TOKEN", BEARER)]:
    subprocess.run(base + [label, "--stdin"], input=value, capture_output=True, text=True, timeout=60)
PY

Plain env (no secrets — argv-safe):

for K in \
  "VENICE_MCP_HTTP=1" \
  "VENICE_MCP_HOST=0.0.0.0" \
  "VENICE_DISABLE_NSFW=0" \
  "VENICE_DEFAULT_CHAT_MODEL=minimax-m3-preview" \
  "VENICE_DEFAULT_IMAGE_MODEL=flux-2-pro" \
  "VENICE_DEFAULT_TTS_MODEL=tts-kokoro" \
  "VENICE_DEFAULT_ASR_MODEL=openai/whisper-large-v3" \
  "VENICE_DEFAULT_VIDEO_MODEL=ltx-2" \
  "VENICE_DEFAULT_MUSIC_MODEL=ace-step-15" \
  "VENICE_HTTP_TIMEOUT_MS=120000" \
  "VENICE_MCP_MAX_SESSIONS=100" \
  "VENICE_MCP_SESSION_TTL_MS=1800000" \
  "PORT=3333" \
  "MEDHA_SERVER_NAME=@medha/mcp-server" \
  "MEDHA_SERVER_VERSION=0.4.0-medha"
do
  railway variable set --service medha --skip-deploys "$K"
done

5. Deploy + attach domain

cd ~/tmp/medha-deploy
railway up --service medha --detach
railway domain --service medha
# → https://medha-production.up.railway.app/mcp

6. Smoke

BEARER=$(cat ~/.config/railway/medha-bearer.token)
URL=https://medha-production.up.railway.app/mcp

curl -sS -i -X POST "$URL" \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}' \
  | head

HTTP 200 with a mcp-session-id UUID header → you're live.

7. Connect an agent

See presets.md for the canonical defaults table. For Claude Desktop / Claude Code CLI / Cursor / Codex CLI / Hermes / Jiva connector recipes, see CONNECTORS.md.

---

Configuration reference

Env	Default	Purpose
VENICE_API_KEY (required)	(none)	Operator's Venice API key. Forwarded as Authorization: Bearer to all upstream calls.
VENICE_SIWX_TOKEN	(none)	Optional SIWE-signed wallet token (x402 mode). Used only when VENICE_API_KEY is unset.
VENICE_MCP_HTTP	(unset)	Set to 1 to enable HTTP mode (binds :3333/mcp).
VENICE_MCP_HOST	127.0.0.1	Bind address. 0.0.0.0 for LAN/Railway.
VENICE_MCP_AUTH_TOKEN	(none)	Bearer required for /mcp when host ≠ loopback. Generate with python3 -c "import secrets; print(secrets.token_hex(32))".
VENICE_MCP_MAX_SESSIONS	100	Cap on concurrent Streamable HTTP sessions.
VENICE_MCP_SESSION_TTL_MS	1800000	Idle session TTL (30 min).
VENICE_HTTP_TIMEOUT_MS	60000	Per-call upstream timeout. Default 120s for video/music latencies.
VENICE_DISABLE_NSFW	0	Set to 1 to remove NSFW capability notes from tool descriptions.
VENICE_DEFAULT_CHAT_MODEL	venice-uncensored	Medhā default: minimax-m3-preview.
VENICE_DEFAULT_IMAGE_MODEL	flux-2-pro	(same as upstream)
VENICE_DEFAULT_TTS_MODEL	tts-kokoro	(same as upstream)
VENICE_DEFAULT_ASR_MODEL	openai/whisper-large-v3	(same as upstream)
MEDHA_SERVER_NAME	@medha/mcp-server	Override the MCP serverInfo.name.
MEDHA_SERVER_VERSION	0.4.0-medha	Override the MCP serverInfo.version.
PORT	3333	Railway-respected; controls the listener.

---

Operator preferences

The operator-curated defaults are baked into the tool descriptions so agents read them on every tools/list call. They are also a single canonical JSON document available via the medha://favorites resource:

# After defining BEARER + SID as in the smoke test:
curl -sS -X POST https://medha-production.up.railway.app/mcp \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"medha://favorites"}}'

See presets.md for the full table with rationale per domain (reasoning / coding / roleplay / vision / longctx / image / music / video / etc.).

The operator prefs are HINTS, not hard rules. Agents you connect can pass model="<any-venice-id>" on any call and the server will forward it. The presets exist to save the agent from re-discovering the operator's taste on every prompt.

---

Workflow prompts (Medhā-only)

Beyond the upstream 3 (uncensored-research, nsfw-creative-writing, image-style-explorer), Medhā ships 4 workflow prompts that guide the agent into known-good multi-tool sequences:

Prompt	Workflow	Default models
medha_music_video_brief	Quote → music gen → 4-12 image frames → video interpolation per frame → optional TTS.	ace-step-15 (music) · flux-2-pro (image) · ltx-2 (video) · tts-kokoro (TTS)
medha_podcast_pipeline	Web search → scrape top URLs → script via chat → TTS.	qwen-3-7-max (chat) · tts-kokoro (TTS)
medha_dashboard_poster	Chat-compose prompt → flux-2-pro → optional bg-remove → optional 2× upscale.	qwen-3-7-max (chat) · flux-2-pro (image)
medha_character_dossier	Dossier + system prompt via roleplay chat → TTS sample → optional avatar image.	venice-uncensored-role-play (chat) · tts-kokoro (TTS) · flux-2-pro (image)

When the agent invokes one of these prompts, MCP returns a single user-role message that lays out the recommended tool-call sequence with the operator's preferred models. The agent then orchestrates from there.

---

Provenance + license

Upstream: github.com/veniceai/venice-mcp-server @ v0.2.0 — MIT-licensed by Venice AI. Medhā is a fork: same code, operator-tuned UX. No warranty or SLA from Venice AI. Use at your own risk.

Maintainer: Vivek M (@vivmuk). Brand: Medhā — Sanskrit medhā (मेधा) = wisdom / intelligence / mental power.