# sarvamai/sarvam-mcp architecture

> Architecture diagram of the GitHub repository sarvamai/sarvam-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sarvamai/sarvam-mcp
- Repository: https://github.com/sarvamai/sarvam-mcp

## Overview

#### 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`.

Main entry points: [`src/sarvam_mcp/server.py`](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/server.py) (MCP application), [`src/sarvam_mcp/tools/__init__.py`](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/__init__.py) (Tool namespaces), [`src/sarvam_mcp/tools/stt.py`](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/stt.py) (Runtime AI tools), [`src/sarvam_mcp/http/client.py`](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/http/client.py) (Shared HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Server"]
  node_entry["Package entry point<br/>Python entry<br/>[__main__.py]"]
  node_server["MCP application<br/>MCP server<br/>[server.py]"]
  node_registry["Tool registry<br/>registration<br/>[_registry.py]"]
  node_tool_namespaces["Tool namespaces<br/>MCP tools<br/>[__init__.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_auth["API key resolution<br/>authentication<br/>[api_key.py]"]
  node_mcp_context["Credential context<br/>MCP boundary<br/>[context.py]"]
  node_observability["Analytics and observability<br/>telemetry<br/>[observability.py]"]
end

subgraph group_runtime["Runtime Services"]
  node_runtime_tools["Runtime AI tools<br/>MCP tool contract<br/>[stt.py]"]
  node_tts_tools["Speech synthesis tools<br/>MCP tool<br/>[tts.py]"]
  node_llm_tools["LLM completion tools<br/>MCP tool<br/>[llm.py]"]
  node_workflows["Dubbing workflows<br/>orchestration<br/>[dub.py]"]
  node_localization["Localization workflows<br/>orchestration<br/>[localize.py]"]
  node_builder_tools["Builder documentation tools<br/>code assistance<br/>[docs.py]"]
  node_audio_uris["Audio URI resolver<br/>resource input<br/>[uris.py]"]
  node_audio_sinks["Audio output sinks<br/>media delivery<br/>[sinks.py]"]
end

subgraph group_sarvam["Sarvam Boundary"]
  node_http_client["Shared HTTP client<br/>REST client<br/>[client.py]"]
  node_sarvam_api{{"Sarvam AI APIs<br/>external API"}}
end

subgraph group_website["Operations Website"]
  node_website_tracking["Usage tracking endpoint<br/>Next.js API route<br/>[route.ts]"]
  node_website_deployment{{"Website Helm deployment<br/>Kubernetes deployment"}}
end

node_entry -->|"launches"| node_server
node_server -->|"initializes"| node_registry
node_registry -->|"registers"| node_tool_namespaces
node_tool_namespaces -->|"exposes"| node_runtime_tools
node_tool_namespaces -->|"exposes"| node_tts_tools
node_tool_namespaces -->|"exposes"| node_llm_tools
node_tool_namespaces -->|"exposes"| node_builder_tools
node_server -->|"loads"| node_config
node_server -->|"uses"| node_mcp_context
node_mcp_context -->|"supplies or requests"| node_auth
node_runtime_tools -->|"authenticates with"| node_auth
node_runtime_tools -->|"calls through"| node_http_client
node_tts_tools -->|"resolves input"| node_audio_uris
node_tts_tools -->|"writes output"| node_audio_sinks
node_tts_tools -->|"calls through"| node_http_client
node_llm_tools -->|"calls through"| node_http_client
node_workflows -->|"composes"| node_runtime_tools
node_localization -->|"composes"| node_runtime_tools
node_config -->|"configures"| node_audio_sinks
node_auth -->|"authorizes"| node_http_client
node_http_client -->|"REST requests"| node_sarvam_api
node_server -.->|"emits signals"| node_observability
node_observability -.->|"reports usage"| node_website_tracking
node_website_deployment -->|"deploys"| node_website_tracking

click node_entry "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/__main__.py"
click node_server "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/server.py"
click node_registry "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/_registry.py"
click node_tool_namespaces "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/__init__.py"
click node_config "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/config.py"
click node_auth "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/auth/api_key.py"
click node_mcp_context "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/auth/context.py"
click node_runtime_tools "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/stt.py"
click node_tts_tools "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/tts.py"
click node_llm_tools "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/llm.py"
click node_workflows "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/workflows/dub.py"
click node_localization "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/workflows/localize.py"
click node_builder_tools "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/code/docs.py"
click node_audio_uris "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/audio/uris.py"
click node_audio_sinks "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/audio/sinks.py"
click node_http_client "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/http/client.py"
click node_observability "https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/observability.py"
click node_website_tracking "https://github.com/sarvamai/sarvam-mcp/blob/main/web/app/api/track/route.ts"
click node_website_deployment "https://github.com/sarvamai/sarvam-mcp/blob/main/helmchart/sarvam-mcp-website/templates/sarvam-mcp-website.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_registry,node_tool_namespaces,node_config,node_auth,node_mcp_context,node_observability toneBlue
class node_runtime_tools,node_tts_tools,node_llm_tools,node_workflows,node_localization,node_builder_tools,node_audio_uris,node_audio_sinks toneAmber
class node_http_client,node_sarvam_api toneMint
class node_website_tracking,node_website_deployment toneRose
```

## Components

### MCP Server

- [Package entry point](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/__main__.py): Python entry · `src/sarvam_mcp/__main__.py`
- [MCP application](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/server.py): MCP server · `src/sarvam_mcp/server.py`
- [Tool registry](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/_registry.py): registration · Centralizes runtime and builder tool discovery. · `src/sarvam_mcp/_registry.py`
- [Tool namespaces](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/__init__.py): MCP tools · `src/sarvam_mcp/tools/__init__.py`
- [Runtime configuration](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/config.py): configuration · Sets API URL, output path, and audio mode. · `src/sarvam_mcp/config.py`
- [API key resolution](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/auth/api_key.py): authentication · Uses environment credentials before credential-file fallback. · `src/sarvam_mcp/auth/api_key.py`
- [Credential context](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/auth/context.py): MCP boundary · Carries or elicits credentials at MCP boundaries. · `src/sarvam_mcp/auth/context.py`
- [Analytics and observability](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/observability.py): telemetry · `src/sarvam_mcp/observability.py`

### Runtime Services

- [Runtime AI tools](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/stt.py): MCP tool contract · Speech, LLM, translation, analytics, vision, and dictionary capabilities. · `src/sarvam_mcp/tools/stt.py`
- [Speech synthesis tools](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/tts.py): MCP tool · `src/sarvam_mcp/tools/tts.py`
- [LLM completion tools](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/tools/llm.py): MCP tool · `src/sarvam_mcp/tools/llm.py`
- [Dubbing workflows](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/workflows/dub.py): orchestration · Composes lower-level calls into voice workflows. · `src/sarvam_mcp/workflows/dub.py`
- [Localization workflows](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/workflows/localize.py): orchestration · `src/sarvam_mcp/workflows/localize.py`
- [Builder documentation tools](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/code/docs.py): code assistance · Exposes documentation, snippets, and curated agent data. · `src/sarvam_mcp/code/docs.py`
- [Audio URI resolver](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/audio/uris.py): resource input · `src/sarvam_mcp/audio/uris.py`
- [Audio output sinks](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/audio/sinks.py): media delivery · Writes generated media according to configured output mode. · `src/sarvam_mcp/audio/sinks.py`

### Sarvam Boundary

- [Shared HTTP client](https://github.com/sarvamai/sarvam-mcp/blob/main/src/sarvam_mcp/http/client.py): REST client · Owns requests, retries, and normalized upstream failures. · `src/sarvam_mcp/http/client.py`
- **Sarvam AI APIs**: external API

### Operations Website

- [Usage tracking endpoint](https://github.com/sarvamai/sarvam-mcp/blob/main/web/app/api/track/route.ts): Next.js API route · `web/app/api/track/route.ts`
- [Website Helm deployment](https://github.com/sarvamai/sarvam-mcp/blob/main/helmchart/sarvam-mcp-website/templates/sarvam-mcp-website.yaml): Kubernetes deployment · `helmchart/sarvam-mcp-website/templates/sarvam-mcp-website.yaml`

## Connections

- Package entry point → MCP application: launches
- MCP application → Tool registry: initializes
- Tool registry → Tool namespaces: registers
- Tool namespaces → Runtime AI tools: exposes
- Tool namespaces → Speech synthesis tools: exposes
- Tool namespaces → LLM completion tools: exposes
- Tool namespaces → Builder documentation tools: exposes
- MCP application → Runtime configuration: loads
- MCP application → Credential context: uses
- Credential context → API key resolution: supplies or requests
- Runtime AI tools → API key resolution: authenticates with
- Runtime AI tools → Shared HTTP client: calls through
- Speech synthesis tools → Audio URI resolver: resolves input
- Speech synthesis tools → Audio output sinks: writes output
- Speech synthesis tools → Shared HTTP client: calls through
- LLM completion tools → Shared HTTP client: calls through
- Dubbing workflows → Runtime AI tools: composes
- Localization workflows → Runtime AI tools: composes
- Runtime configuration → Audio output sinks: configures
- API key resolution → Shared HTTP client: authorizes
- Shared HTTP client → Sarvam AI APIs: REST requests
- MCP application → Analytics and observability: emits signals
- Analytics and observability → Usage tracking endpoint: reports usage
- Website Helm deployment → Usage tracking endpoint: deploys