AI agents' integration with Integrated Development Environments (IDEs) is already part of the usual workflow. Most software engineers use AI auto-completion tools like GitHub Copilot, and many use "vibe coding."
AI agent instructions are commonly seen in many projects. We often find files like AGENT.md, AGENTS.md, CLAUDE.md, and others. These files usually contain instructions for AI agents on how to interact with the project, what tools to use, and any specific guidelines. For example, they might define how to use the codebase, which libraries are utilized, what the project goals are, and so on.
Ideal instructions should allow an AI agent to complete complex tasks autonomously, such as: "I need a new feature that lets users add commands to text pages on the website." Ideally, the AI agent should have all the necessary information, such as "how to add new API endpoints," "how to add new database models," "how to support a database migration," and "how to link the UI to the backend."
However, I haven't seen truly effective working instructions. Usually, all this information is too vast for a single instruction file. If we describe every detail, this information will overload the AI agent's context.
We must remember that an AI agent's instructions are sent to the Large Language Model (LLM) along with every user prompt. Instructions that are too long distract the model's attention because they always contain everything, not just what's relevant at the moment.
Solution: A Custom MCP Server for Every Code Project
And here's the idea: why not create a custom Model Context Protocol (MCP) server for every project? This can replace AI agent instruction files and offer much greater flexibility.
Before going further, if you're not familiar with the MCP protocol, I recommend reading the official documentation: https://modelcontextprotocol.io/docs/getting-started/intro.
There are several advantages to using an MCP server for every project:
- Dynamic Instructions: An MCP server can provide dynamic instructions upon request from the LLM. It could support a tree of knowledge and provide only the relevant information for the current task. The LLM will decide which "article" to read, and the MCP server will provide only that specific content.
- Access to Framework Tools: Many software frameworks have their own tools for working with the codebase. For example, Django has management commands to create models, run migrations, start a development server, and so on. The MCP server can expose these tools to the LLM, allowing it to use them directly.
- Project-Specific Logic: The MCP server can implement project-specific logic, such as understanding the architecture, coding conventions, and best practices. This helps the LLM generate consistent code. For instance, the MCP server can have an
add_new_featuretool. If we know that a new feature in our project means adding an "API router with a default endpoint," a "database model," "unit tests," and so forth, the MCP server can implement all this logic, so the LLM simply calls this single tool. - Additional Tools: Many projects have their own tools, such as linters, formatters, test runners, package builders, and "GUI builders." The MCP server can expose these tools to the LLM, allowing it to use them directly. We can prompt the LLM with commands like "run tests," "build package," or "format code," and the MCP will execute the project's specific tools.
- Integration with Services: Many projects are integrated with external services, like CI/CD pipelines, cloud providers, monitoring tools, and project management tools. The MCP server can implement tools to interact with these services, enabling the LLM to manage deployments, monitor performance, and handle incidents directly from the codebase. Note: often these services have their own MCP servers, so having a custom tool in a project's MCP might seem redundant. However, I see benefits in having a unified interface for all project-related tools and services, which I'll explain below.
- Connection to Cooperative Repositories: Many projects have related repositories, such as documentation sites, design systems, shared libraries, and microservices. The MCP server can implement tools to interact with these repositories, allowing the LLM to access and update related resources seamlessly.
One Single Custom MCP Server vs. Multiple Standard MCP Servers
Someone might ask, "Why not use multiple standard MCP servers, each for its own service?" For example, we could have one MCP server for codebase management, another for CI/CD, and another for the cloud provider, installing them from standard MCP server repositories.
I disagree with this for a simple reason: based on my experience, a "standard MCP server" often includes many tools, but in practice, you only need a few. Even those few may need to work slightly differently to fit your project's needs. If you connect multiple standard MCP servers, you'll end up with many unneeded tools. This overloads the LLM; we know that too many tools can confuse the model and make it harder to find the right one for the task at hand.
Having one single custom MCP server for the project allows you to include only the necessary tools and implement them in a way that perfectly fits the project's needs. This makes the interaction with the LLM more efficient and effective. We should remember that adding tools to an MCP server is not difficult; it's usually just a wrapper around an API call or a command-line tool.
Knowledge Book Tool
Let's look closer at the "replacement of instructions" feature. The MCP server can implement a special tool called knowledge_book. This tool can provide the LLM with relevant information about the project based on the current context.
The idea is that the knowledge is organized hierarchically, like a book with chapters and sections. Each section contains information about a specific topic, such as "how to add a new API endpoint," "how to run tests," or "how to deploy the project."
When the LLM needs information, it calls the knowledge_book index, then calls it again with a specific section, and can then retrieve the relevant subsection, and so on.
Information in the book can include anything relevant to the project, such as code examples for different cases: "adding a new database model," "creating a new API endpoint," "running migrations," "setting up CI/CD," and so on.
We present this information to the AI agent, but it should be presented in a way we would use for a trainee developer. The information should be clear, concise, and easy to understand. It should also include code examples, best practices, and common pitfalls to avoid. If a trainee developer can understand and use this information, then the LLM will be able to use it as well.
Example: index page of the knowledge book, if the tool "description" is always present in LLM context:
# Knowledge Book for Project X
This knowledge book contains information about Project X, including how to add new features, run tests, deploy the project, and more.
The argument `section` allows you to specify which section of the book to retrieve. If no section is specified, the index page is returned. The section must include the number of the section, e.g., "1. Introduction", "3.1. Backend Development", etc.
## Table of Contents
1. Introduction
2. Setting Up the Development Environment
3. Project Structure
4. Adding New Features
4.1. Adding API Endpoints
4.2. Creating Database Models
4.3. Running Migrations
5. Testing
6. Deployment
7. CI/CD Integration
8. Project Management Tools
9. External Services Integration
10. Related Repositories
Possible Implementation Approach
This custom MCP server can be included in a project codebase, perhaps in a folder like .mcp or something similar. The MCP server can be implemented using any programming language; it doesn't have to be the same as the project language.
It's normal that the MCP server will be extended over time as the project evolves. New tools can be added, and existing tools can be modified to fit the project's needs. The knowledge book can also be updated as new information becomes available.
Usage and configuration of the MCP server depends on the specific project requirements and the development environment.
Conclusion
Creating a custom MCP server for every project can significantly enhance the interaction between AI agents and codebases. It allows for dynamic instructions, access to project-specific tools, and a unified interface for managing various services and repositories. By implementing a knowledge book tool, we can provide the LLM with relevant information in a structured manner, making it easier for the model to understand and work with the project.
