Usage — API / CLI / MCP¶
documentdb-mcp exposes the same capability three ways: as MCP tools an agent
calls, as a Python API (DocumentDBApi) the operator import, and as a CLI / agent
server. The ecosystem role and the tool modules are covered in Overview.
As an MCP server¶
Once deployed, the server registers one typed tool per database operation.
Each module is togglable with its environment switch (all default to True):
| Module | Env switch | Action-routed methods |
|---|---|---|
| System | SYSTEMTOOL |
binary_version, list_databases, run_command, create_database, drop_database |
| Collections | COLLECTIONSTOOL |
list_collections, create_collection, drop_collection, rename_collection |
| Users | USERSTOOL |
create_user, drop_user, update_user, users_info |
| CRUD | CRUDTOOL |
find, find_one, insert_one, insert_many, update_one, update_many, replace_one, delete_one, delete_many, count_documents, find_one_and_update, find_one_and_replace, find_one_and_delete |
| Analysis | ANALYSISTOOL |
distinct, aggregate |
Example agent prompts that map onto these tools:
- "List the databases on this server" → System (
list_databases) - "Find the 10 most recent orders for customer 42" → CRUD (
find) - "How multiple documents match status = active in the orders collection?" → CRUD (
count_documents) - "What are the distinct values of
countryin the users collection?" → Analysis (distinct)
As a Python API¶
DocumentDBApi is a pymongo-backed facade that groups the system, collections,
users, CRUD, and analysis operations. Build one straight from the environment with
get_client():
from documentdb_mcp.auth import get_client
api = get_client() # reads MONGODB_URI / MONGODB_HOST / MONGODB_PORT
…or build it explicitly from a pymongo client:
import pymongo
from documentdb_mcp.api_client import DocumentDBApi
api = DocumentDBApi(client=pymongo.MongoClient("mongodb://localhost:27017/"))
# System reads
print(api.binary_version()) # server build version
print(api.list_databases()) # ["admin", "documentation_db", ...]
print(api.list_collections("documentation_db"))
# CRUD reads — ObjectIds are serialized to strings
docs = api.find("documentation_db", "orders", {"status": "active"}, limit=10)
one = api.find_one("documentation_db", "orders", {"_id": "65a..."})
n = api.count_documents("documentation_db", "orders", {"status": "active"})
# Analysis reads
countries = api.distinct("documentation_db", "users", "country", {})
pipeline = [{"$group": {"_id": "$status", "n": {"$sum": 1}}}]
summary = api.aggregate("documentation_db", "orders", pipeline)
Writes¶
Write operations are available on the same client; each returns a status string:
api.insert_one("documentation_db", "orders", {"status": "active", "total": 42})
api.update_one(
"documentation_db", "orders", {"_id": "65a..."}, {"$set": {"status": "shipped"}}
)
api.delete_one("documentation_db", "orders", {"_id": "65a..."})
As a CLI / agent¶
The MCP server console script doubles as a CLI entry point, and the package ships a Pydantic-AI graph agent:
Each connector reads its connection settings from the environment (see
.env.example)
and the server remains inactive when no reachable endpoint is configured.