Client: Open-source community project (self-initiated) Timeline: 2 weeks from concept to npm publication Role: Sole architect and developer Technologies: TypeScript, Node.js, Ollama SDK, Model Context Protocol, Zod validation

The AI tooling landscape has evolved rapidly, with Model Context Protocol (MCP) emerging as the open standard for integrating AI assistants with external capabilities. Applications like Claude Desktop, Claude Code, Cursor, Windsurf and VS Code's Cline extension support MCP, but a critical gap existed.

Organisations wanting to leverage locally-hosted large language models through Ollama had no production-ready pathway to integrate these models into their MCP-compatible workflows. The alternatives were stark: build custom middleware from scratch (weeks of development), accept vendor lock-in to cloud-only solutions, or simply go without local AI capabilities.

For teams with privacy requirements, cost constraints, or the need for custom fine-tuned models, this gap represented a genuine blocker to adoption.

I designed and built a comprehensive MCP server that exposes the complete Ollama SDK as discoverable tools, creating a seamless bridge between local LLM infrastructure and the broader MCP ecosystem.

Production-Ready from Day One: This wasn't a proof-of-concept. Every architectural decision prioritised reliability, maintainability, and real-world deployment scenarios.

Zero-Configuration Extensibility: A hot-swap autoloader pattern means new tools can be added by simply dropping files into the tools directory: no server modifications required.

Graceful Failure Handling: Comprehensive retry logic with exponential backoff, rate-limit header compliance, and 30-second request timeouts prevent the cascading failures that plague less mature integrations.

Hybrid Flexibility: Organisations can run sensitive inference locally whilst still accessing cloud-based web search and content extraction—privacy where it matters, connectivity where it helps.

14 Production Tools covering the complete Ollama SDK:

Model management: list, show, pull, push, copy, delete, create

Model operations: chat, generate, embeddings, process status

Web integration: search and fetch via Ollama Cloud

Intelligent retry system handling HTTP 429, 500, 502, 503, and 504 errors

Support for both Retry-After header formats (delay-seconds and HTTP-date)

Exponential backoff with full jitter when server guidance unavailable

Request timeouts preventing hung connections

Drop-in configuration for Claude Desktop and Cline

npm package for straightforward global installation

Comprehensive documentation with usage examples

TypeScript throughout with Zod schema validation

The project achieved 96.37% test coverage across statements and lines, with 100% function coverage across all 14 implemented tools. The codebase maintains a minimal dependency footprint, relying only on the Ollama SDK, MCP SDK, and Zod for validation. From initial concept to npm publication took just 2 weeks.

The server is now publicly available via npm, with configuration requiring just 6 lines of JSON for most deployments. The architecture has proven extensible: adding new tools requires only creating a single file with the standardised export pattern.

Challenge: Ollama's API can experience transient failures, particularly under load or when pulling large models.

Solution: Implemented a sophisticated retry mechanism that respects server-provided retry guidance, falls back to jittered exponential backoff, and distinguishes between retryable transient errors and permanent failures requiring user intervention.

Challenge: MCP tool discovery needs to be dynamic to support extensibility without server restarts.

Solution: Designed an autoloader that scans the tools directory at startup, validating each tool's exported definition against a strict interface. New capabilities become available simply by adding files: zero configuration changes required.

Challenge: Balancing local privacy with cloud capability requirements.

Solution: Hybrid mode architecture allows the server to connect to local Ollama instances for inference whilst still enabling cloud-only features (web search, content fetch) when an API key is provided.

This project reflects my approach to software engineering:

Architectural Thinking: Solutions designed for extensibility and maintenance, not just initial delivery. The autoloader pattern means this codebase can grow without accumulating technical debt.

Production Mindset: Comprehensive error handling, meaningful test coverage, and documentation aren't afterthoughts: they're integral to shipping software that teams can actually depend upon.

Standards Awareness: Building on open protocols (MCP) rather than proprietary integrations ensures longevity and interoperability.

Pragmatic Trade-offs: The hybrid mode exemplifies meeting users where they are: supporting both privacy-conscious local deployments and convenience-focused cloud usage without forcing a choice.

If your organisation is looking to:

Integrate local or cloud AI capabilities into existing toolchains

Build custom MCP servers for proprietary systems or APIs

Extend Claude Desktop, Cline, or other MCP-compatible applications

Develop reliable middleware with production-grade error handling and test coverage

I would welcome the opportunity to discuss how this approach might address your specific requirements.

GitHub Repository: github.com/rawveg/ollama-mcp

npm Package: npmjs.com/package/ollama-mcp