Learn how MongoDB Agent Skills augment AI coding assistants with MongoDB-specific expertise for document modeling, query generation, schema optimization, and database operations.
This repository contains a deliberately simple Spring Boot application with an intentionally imperfect MongoDB schema. Rather than focusing on the application itself, the goal is to demonstrate how AI coding assistants use MongoDB Agent Skills—and optionally the MongoDB MCP Server—to understand, improve, and extend real MongoDB applications.
This repository demonstrates how MongoDB Agent Skills help AI coding assistants:
- Review existing MongoDB document models
- Detect MongoDB schema anti-patterns
- Recommend embedding versus referencing
- Explain MongoDB design decisions
- Generate aggregation pipelines from natural language
- Implement schema improvements
- Update application code after schema changes
- Generate Spring Data MongoDB repositories and queries
- Inspect a live MongoDB deployment through the MongoDB MCP Server
Natural Language
│
▼
+--------------------------------+
| AI Coding Assistant |
| OpenCode / Claude / Cursor |
+--------------------------------+
│
Automatically invokes
│
▼
+--------------------------------+
| MongoDB Agent Skills |
+--------------------------------+
│
(optional)
▼
+--------------------------------+
| MongoDB MCP Server |
+--------------------------------+
│
▼
+---------------------------------------------------+
| Spring Boot Application |
| Customer + Address REST API |
+---------------------------------------------------+
│
▼
+--------------------------------+
| MongoDB Atlas |
+--------------------------------+
MongoDB Agent Skills provide MongoDB-specific reasoning and guidance to the coding assistant. When configured, the MongoDB MCP Server allows the assistant to inspect a live MongoDB deployment, understand the current schema, examine indexes, and perform database operations alongside code changes.
- Java 17+
- Maven 3.9+
- Node.js
- MongoDB Atlas Cluster
- OpenCode (or another supported Agent Skills-compatible coding assistant)
git clone https://github.com/mongodb-developer/agentskilldemo.git
cd agentskilldemoExport your Atlas connection string.
export MONGODB_URI="<your connection string>"The application uses the standard MongoDB application name:
spring.data.mongodb.uri=${MONGODB_URI}?appName=devrel-java-agent-skills-demonpx skills add mongodb/agent-skillsFollow the official setup guide:
https://www.mongodb.com/docs/mcp-server/get-started/
The MCP Server allows your coding assistant to inspect collections, sample documents, indexes, and other database metadata while working on your application.
mvn spring-boot:runFrom the project root:
opencodeYou can verify the MongoDB Agent Skills are available by running:
/skills
This repository is designed to be explored through natural language.
Try asking your coding assistant:
Optimize the MongoDB schema.
Explain the MongoDB document model.
What MongoDB anti-patterns do you see?
Should these documents be embedded or referenced?
Generate an aggregation that groups customers by city.
Implement your recommended schema changes.
Update the existing data to match the new schema.
Explain why embedding is a better design here.
Generate a REST endpoint to search customers by city.
These prompts showcase how MongoDB Agent Skills provide more accurate, MongoDB-specific guidance than a general-purpose coding assistant.
The application intentionally contains a suboptimal document model.
Initially:
- Customers are stored in one collection.
- Addresses are stored in another collection.
- Customers reference addresses by ObjectId.
While this works, it is not the ideal MongoDB design for this workload. Since customer addresses are almost always retrieved together with the customer, MongoDB Agent Skills recommend embedding the addresses directly within the customer document.
The goal is not to build the perfect application—the goal is to show how MongoDB Agent Skills recognise this design, explain the reasoning, and help implement the improvement.
src
├── controller
├── model
├── repository
├── service
└── resources
The project intentionally remains small so the focus stays on the interaction between the AI coding assistant and MongoDB Agent Skills.
This repository focuses on document modelling rather than CRUD operations.
MongoDB's flexible document model makes it possible to demonstrate one of the most important schema design decisions: embedding versus referencing.
The sample application intentionally begins with a referenced model so MongoDB Agent Skills can identify the anti-pattern and recommend embedding the addresses directly within the customer document. This allows the coding assistant to explain the trade-offs, update the Java models, modify repositories and services, and optionally migrate the data using the MongoDB MCP Server.
Relevant MongoDB components include:
model/repository/service/
Useful documentation:
- https://www.mongodb.com/docs/manual/data-modeling/
- https://www.mongodb.com/docs/manual/data-modeling/concepts/embedding-vs-references/
This repository accompanies the tutorial:
Getting Started with MongoDB Agent Skills
It demonstrates the complete workflow:
- Install MongoDB Agent Skills
- Configure the MongoDB MCP Server
- Open an existing Spring application
- Review the schema
- Improve the document model
- Generate MongoDB queries
- Implement the proposed changes
- MongoDB Agent Skills Documentation
- MongoDB MCP Server Documentation
- MongoDB Agent Skills GitHub Repository
- Spring Data MongoDB Documentation
This project is licensed under the MIT License.