sarvam-mcp

Sarvam MCP

Drive sarvam-mcp. Prefer MCP tools over inventing HTTP/SDK calls for live work.

Procedure

Copy and track:

- [ ] 1. MCP available? If no → read references/install.md (or fall back to SDK skills)
- [ ] 2. Namespace: live action → sarvam_tools_*; write/lookup code → sarvam_code_*
- [ ] 3. Prefer a composite if the task spans STT/translate/TTS/LLM
- [ ] 4. Call the tool (absolute paths; BCP-47 codes)
- [ ] 5. On auth error → sarvam_tools_set_api_key; on param error → fix and retry
- [ ] 6. Return the result path/text; mention observability only if debugging

1. Namespace (mandatory)

User wants…	Namespace	Example
Sarvam to do it now	sarvam_tools_*	"Translate this to Tamil"
Help writing code / API facts	sarvam_code_*	"How do I call TTS from Python?"

Never use sarvam_code_* for a live translate/TTS/STT request. Never burn sarvam_tools_* credits just to draft code unless the user asked for a live demo.

2. Pick the tool (defaults)

Composites first — do not hand-chain STT → translate → TTS:

Task	Tool
Spoken reply to audio	sarvam_tools_voice
Dub into another Indic language	sarvam_tools_dub
Localize JSON/YAML/PO/etc.	sarvam_tools_localize
Q&A / summary over audio	sarvam_tools_recall

Atomic runtime (use when no composite fits):

Task	Tool
Transcribe	sarvam_tools_stt_transcribe
Speech → English	sarvam_tools_stt_translate
Audio >~30s / diarization	sarvam_tools_stt_batch_submit → _stt_batch_status
Speak text	sarvam_tools_tts_speak
Translate text	sarvam_tools_translate
Transliterate / LID / analytics	sarvam_tools_transliterate / _identify_language / _text_analytics
Chat complete	sarvam_tools_llm_complete
Document intelligence	sarvam_tools_vision_extract → _vision_job_status
Pronunciation dicts	sarvam_tools_pronunciation_*
Set / rotate API key	sarvam_tools_set_api_key

Build-time (coding help):

Task	Tool
Unsure which model/lang	sarvam_code_recommend_model
Endpoint shape	sarvam_code_api_reference
Snippet	sarvam_code_snippet
Speakers / languages	sarvam_code_speakers / _languages
Validate draft body	sarvam_code_validate_request
Docs search / pricing	sarvam_code_search_docs / _pricing

Coding flow: recommend_model → snippet or api_reference → validate_request.

For parameters and env knobs, read references/tools.md.

3. Defaults (use unless user overrides)

Setting	Default
STT model	saaras:v3
TTS model / speaker	SDK code: bulbul:v4-flash / persona ID (aparna_hi_customer). Live tts_speak / tts_stream / voice / dub (sarvam-mcp ≥ 0.2.11): model / tts_model = bulbul:v4-flash + persona ID; omit the speaker for the shubh_enhi_ads default. On older servers the schema enums only bulbul:v3 + short names (priya) — check the connected schema and do not send a v4 persona ID unless it lists bulbul:v4-flash.
LLM	sarvam-30b (use sarvam-105b for hard reasoning)
Translate model	mayura:v1 (switch to sarvam-translate:v1 for broader Indic coverage)
Audio path	Absolute local path
Language codes	BCP-47 (hi-IN, ta-IN, od-IN not or-IN)

4. Auth

Key sources (env wins): SARVAM_API_KEY, or ~/.sarvam/credentials (api_key = sk_...).

Dashboard: https://dashboard.sarvam.ai/key-management

On auth failure:

1. sarvam_tools_set_api_key with empty api_key → instructions + link
2. Call again with sk_... → persists to ~/.sarvam/credentials

Wire auth is api-subscription-key — never invent Authorization: Bearer.

Examples

Live translate

User: "Translate 'Good morning' to Hindi."

→ sarvam_tools_translate with input, source_language_code=en-IN, target_language_code=hi-IN. Return translated_text.

Live TTS

User: "Say नमस्ते in Hindi."

→ sarvam_tools_tts_speak with native-script text, target_language_code=hi-IN. Prefer model=bulbul:v4-flash with a persona ID (aparna_hi_customer) when the tool schema lists it (sarvam-mcp ≥ 0.2.11); on older servers use speaker=priya on bulbul:v3. Return the audio path.

Dub

User: "Dub this clip into Tamil" + path.

→ sarvam_tools_dub with audio_path, target_language_code=ta-IN — not STT + translate + TTS separately.

Code help

User: "Show a Python TTS example."

→ sarvam_code_snippet with api=tts, language=python (not sarvam_tools_tts_speak unless they want audio now).

Gotchas

Mistake agents make	Correct behavior
Invent curl/SDK for a live ask	Call sarvam_tools_* when MCP is connected
Hand-chain STT→translate→TTS	Use voice / dub / localize / recall
REST STT on long files	Use stt_batch_* above ~30s
TTS target outside ~11 langs	Check with sarvam_code_languages (api=tts); STT has ~23
v2 speaker on Bulbul v3	Use priya/shubh or sarvam_code_speakers
v3 short name on bulbul:v4-flash (or a v4 persona on v3)	Speaker/model mismatch is rejected. v4-flash takes persona IDs only (aparna_hi_customer); v3 takes shubh / priya. Check sarvam_code_speakers with model=.
pitch / loudness	pitch −0.5–0.5, loudness 0.1–2.5, pace 0.5–2.0; out-of-range values are rejected. Accepted on both v3 and v4-flash (live-verified 2026-10-06).
Romanized Indic for TTS	Prefer native script
output_script on sarvam-translate:v1	mayura:v1 only
Relative audio paths	Prefer absolute paths; or audio_base64/audio_url + filename
Assume output cwd	Files go under SARVAM_MCP_BASE_PATH (default ~/Desktop) unless tool returns another path
Stale tool names without _tools/_code	Match the connected server's tool list

When MCP is missing

1. Read references/install.md and help the user connect the server.
2. If they only need code: use sibling skills translate/text, translate/document, speech-to-text, text-to-speech, chat, or https://docs.sarvam.ai/llms.txt.

References (load on demand)

File	Read when
references/install.md	MCP not connected, setup/troubleshoot, or user names a client
references/tools.md	Choosing parameters, env vars, or an uncommon tool