Ali Zahmatkesh

Posted on Jul 8 Originally published at github.com

Building a Free AI Coding Assistant with MCP and LSP: A Practical Guide

#ai #agents #opensource #productivity

As developers, we're constantly looking for tools that can help us code faster and better. AI coding assistants like GitHub Copilot, Cursor, and Claude are great, but they often come with recurring costs and privacy concerns. What if you could build your own AI coding assistant that's:

Completely free to use.
Offline-capable (no data leaves your machine).
Extensible with external tools and deep code understanding?

In this guide, I'll show you how I built Coding Agent Free, an open-source AI coding assistant that combines free LLM providers with two powerful protocols: MCP (Model Context Protocol) and LSP (Language Server Protocol). Whether you're a developer looking to understand how these protocols work, or someone who wants to use a free and private AI assistant, this guide is for you.

🚀 What You'll Learn

What MCP and LSP are and why they matter for AI coding assistants.
How to set up a free, private AI coding assistant on your own machine.
How to connect it to your IDE (VSCode, Cursor, Continue.dev).
How to extend its capabilities with external tools and language servers.

🤖 What is Coding Agent Free?

Coding Agent Free is an open-source AI coding assistant that runs locally (in your terminal or via a web UI). It supports:

13+ LLM providers: OpenRouter, Groq, Google Gemini, DeepSeek, Mistral, Anthropic, Together AI, Perplexity, xAI, Cohere, and local models (Ollama, LM Studio, Llama.cpp).
Auto-fallback: If one provider hits a rate limit, it automatically switches to the next one.
MCP (Model Context Protocol): Connect to external tools (filesystem, GitHub API, databases, custom servers) dynamically.
LSP (Language Server Protocol): Understand your code semantically—not just text search.
Offline mode: With local models, no data leaves your device.
OpenAI-compatible API: Use it as a local proxy for Cline, Continue.dev, or Cursor.

📦 Note: It's packaged as a standalone binary (no Node.js required) for Windows, Linux, and macOS.

🧠 Why MCP and LSP Matter

Most AI coding tools are chat wrappers—they send your code as text and the LLM does its best to understand it. This approach has two major limitations:

No context awareness: The AI doesn't understand your codebase structure, types, or dependencies.
No tool interaction: The AI can't reach out to external services (databases, APIs, version control) on its own.

MCP and LSP solve these problems.

What is MCP?

Model Context Protocol (MCP) is a protocol that allows AI assistants to interact with external tools and services. Think of it as a "universal plugin system." An AI can call MCP servers to perform actions like:

Reading/writing files.
Querying a database.
Interacting with GitHub.
Running custom scripts.

In Coding Agent Free, MCP servers are configured via a ~/.coding-agent/mcp-servers.json file. Each server provides a set of "tools" that the AI can use.

Example MCP Configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

With this, your AI assistant can directly manipulate files or create GitHub issues.

What is LSP?

Language Server Protocol (LSP) is the backbone of modern IDEs. It provides deep code intelligence—like auto-completion, go-to-definition, and finding references—in a language-agnostic way. When your AI assistant has LSP integration, it can:

Get accurate code definitions (not just text search).
Find all references to a variable or function.
Hover over symbols to see type information and documentation.
Retrieve diagnostics (compile errors and warnings).

Example LSP Tool Calls in Action:

User: "Find all the places where `calculateTotal` is used."
Agent: Calls `code_references` on `calculateTotal` and gets a structured list.
Agent: "The function is used in 3 files: `math.ts`, `dashboard.tsx`, and `utils.ts`."

📦 Setup Guide

Here's how to set up Coding Agent Free and start using it with your IDE.

1. One‑Line Setup (Recommended)

If you have Node.js installed:

npx create-coding-agent@latest my-assistant
cd my-assistant
npm run setup   # Interactive wizard (choose your provider, set API keys)
npm start

The setup wizard will walk you through selecting an LLM provider and configuring your API keys.

2. Using the Standalone Binary

If you don't want to install Node.js, you can download the standalone binary from the Releases page for your OS (Windows, Linux, macOS) and run it directly.

🔌 Integrating with Your IDE

One of the best features is the ability to use Coding Agent Free as a local proxy for any OpenAI‑compatible IDE plugin.

For Cursor, Continue.dev, or Cline

Run the setup script:

npm run setup-ide

This will automatically configure your IDE to use http://localhost:3000 as the OpenAI endpoint. You can then ask questions about your codebase directly from your editor.

Manual Configuration

You can also manually set the base URL in your IDE's settings:

Base URL: http://localhost:3000
API Key: any non‑empty string works (since it's local).

🛠️ Deep Dive: MCP in Action

Let's see MCP in practice. Suppose you have a GitHub MCP server configured. You can ask your assistant:

User: "Open a new issue titled 'Add dark mode' with the description 'We need to support dark mode across the dashboard'."

Agent: Calls the GitHub server's `create_issue` tool.
Agent: "Done. Issue #42 has been created."

The agent didn't just respond with text—it interacted with an external system based on your request. This is what MCP enables.

Adding Custom MCP Servers

You can add any MCP‑compatible server by adding it to mcp-servers.json:

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["path/to/mcp-mysql-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "root"
      }
    }
  }
}

After adding the server, your assistant can query your database directly.

🧩 LSP: Deep Code Understanding

LSP is what makes Coding Agent Free "intelligent" about your code. Here's how it works:

When you start the agent, it launches the appropriate language server for each file type (e.g., typescript-language-server for .ts files, pyright for Python, rust-analyzer for Rust, etc.).
The agent can then call LSP tools:
- code_definition: Find the definition of a symbol.
- code_references: Find all references to a symbol.
- code_hover: Get type info and documentation.
- lookup_symbol: Search for a symbol across files.
- get_diagnostics: Retrieve compile errors and warnings.

Example Workflow

Prompt: "Fix all linting errors in main.ts."

Agent calls get_diagnostics on main.ts.
LSP server returns a structured list: "Error on line 12: 'foo' is not defined. Warning on line 20: Unused variable 'bar'."
Agent asks for more info using code_hover on the undefined variable to understand the intended type.
Agent generates a fix and calls write_file with the corrected code.

The agent is no longer guessing. It's working with accurate, compiler‑level information.

💡 Lessons Learned

Building this project taught me a few things:

Free-tier LLMs are powerful: With auto‑fallback, you can achieve near‑perfect uptime using multiple free providers.
MCP is a game changer: It turns a chat assistant into a real agent that can perform actions across your entire development workflow.
LSP is the missing piece: Semantic understanding of code makes the AI much more reliable and useful.
Local-first is viable: With local models, you get privacy and offline capability without sacrificing much quality.

🔧 Future Roadmap

I'm actively working on:

More LSP languages: Java (jdtls), C# (OmniSharp), PHP (intelephense).
Skills system: Allow users to define reusable skills in SKILL.md files (inspired by crush).
Better TUI: A terminal-based UI with richer interaction.
Plugin ecosystem: Let the community build and share new tools.

🙌 How to Contribute

Coding Agent Free is fully open-source and welcomes contributions. You can help by:

Submitting bug reports or feature requests on GitHub Issues.
Improving documentation or writing tutorials.
Adding support for new MCP servers or LSP languages.
Starring the repo to help others find it.

📚 Resources

🏁 Conclusion

Building your own AI coding assistant is now easier than ever, thanks to free LLMs, MCP, and LSP. You get:

Full privacy and control.
Zero recurring costs.
Extensibility via external tools and language servers.
Deep code understanding that makes the AI more reliable.

I encourage you to try it out, tinker with it, and perhaps contribute back to the project. The best way to learn how these protocols work is to build something with them.

maz557 / coding-agent-free

Interactive AI coding agent using free OpenRouter models with real tool calling

Coding Agent Free

Why This Agent? • Install • Usage • CLI • Web • 📘 Guide

An interactive AI coding assistant that runs in your terminal or web browser — powered by free cloud APIs and local models (Ollama, LM Studio, Llama.cpp). It reads, writes, searches, copies, moves, and deletes files, and runs shell commands — all through natural language tool calling. Includes MCP (Model Context Protocol) and LSP (Language Server Protocol) support for extensibility and deep code understanding.

💡 Offline-ready: With a local server, the agent works fully offline — no internet required, no data leaves your machine.

🧠 Why Coding Agent Free?

Problem	Solution
Coding assistants cost $20/month (ChatGPT+, Claude Pro)	100% free — uses free-tier OpenRouter, Groq, Google, DeepSeek, Mistral + local models
One provider goes down / rate-limited	13 providers — auto-fallback on 429 + manual `/model <n>`
No internet access / restricted region

…

View on GitHub

Happy coding! If you have questions, feel free to reach out in the GitHub discussions.

DEV Community