sarvamai/sarvam-mcp

Purpose and Invocation

sarvam-mcp is a Python 3.11+ MCP server that makes Sarvam AI APIs callable as MCP tools by desktop/editor clients. The package is launched through its console/module entry point, then communicates over the MCP transport used by the host client.

Paths: src/sarvam_mcp/__main__.py, src/sarvam_mcp/server.py, pyproject.toml.

Server Composition and Tool Registration

The server builds the MCP application and registers two tool namespaces: runtime API tools and builder/code-assistance tools. The registry centralizes discovery/registration rather than exposing service modules directly.

Paths: src/sarvam_mcp/server.py, src/sarvam_mcp/_registry.py, src/sarvam_mcp/tools/__init__.py.

Authentication and Runtime Configuration

Configuration establishes the Sarvam API base URL, output base path, and audio output mode. Authentication resolves an API key from SARVAM_API_KEY first, with credential-file fallback; context/elicit modules support carrying or requesting credentials at MCP boundaries.

Paths: src/sarvam_mcp/config.py, src/sarvam_mcp/auth/api_key.py, src/sarvam_mcp/auth/context.py.

Sarvam API Boundary

Runtime tools translate MCP inputs into Sarvam REST calls through a shared HTTP client. The HTTP layer owns request behavior, error normalization, and retry policy, isolating upstream API failures and transport details from individual tools.

Paths: src/sarvam_mcp/http/client.py, src/sarvam_mcp/http/errors.py, src/sarvam_mcp/http/retry.py.

Runtime AI Capability Tools

Service-specific MCP tools cover speech-to-text, text-to-speech, translation/transliteration/language ID, LLM completions, text analytics, vision job submission/status, and pronunciation dictionaries. Tool modules are the primary contract boundary presented to MCP clients.

Paths: src/sarvam_mcp/tools/stt.py, src/sarvam_mcp/tools/tts.py, src/sarvam_mcp/tools/llm.py.

File and Audio Handling

Audio-oriented tools resolve input URIs and write generated media through configurable sinks. This separates remote API payloads from local file/resource delivery and honors the configured MCP base path/output mode.

Paths: src/sarvam_mcp/audio/uris.py, src/sarvam_mcp/audio/sinks.py, src/sarvam_mcp/tools/vision.py.

Higher-Level Workflows and Builder Tools

Workflows compose lower-level runtime calls into voice, dubbing, localization, and recall operations. Separately, code tools expose Sarvam documentation, snippets, and curated data for agents generating API-integrated applications.

Paths: src/sarvam_mcp/workflows/dub.py, src/sarvam_mcp/workflows/localize.py, src/sarvam_mcp/code/docs.py.

Observability and Deployment Surfaces

The Python server emits analytics/observability signals. A separate Next.js website supplies health/ready endpoints and usage tracking, packaged for Kubernetes via Helm; it appears operationally separate from the MCP process.

Paths: src/sarvam_mcp/analytics.py, src/sarvam_mcp/observability.py, web/app/api/track/route.ts, helmchart/sarvam-mcp-website/templates/sarvam-mcp-website.yaml.