Build Your First CRUD API with Node.js, MongoDB, and Claude Code

Atlas Ephemeral Clusters let you create a temporary, free MongoDB Atlas database with a single API call, with no account or API keys. In this tutorial, Claude Code provisions an ephemeral cluster, builds a Fastify CRUD API against it, and then you claim the cluster to keep your data.

You know the free sample stations at the warehouse club? Nobody hands you a clipboard before you get the tiny cup of ravioli. Nobody asks you to verify your email address, pick a subscription tier, or configure network access rules. You taste the ravioli. Then you decide if it goes in the cart.

Now think about the last time you wanted to try an idea against a real cloud database. Create an account. Verify the email. Create an organization. Create a project. Pick a cloud provider and a region. Create a database user. Allow-list your IP address. Somewhere around step six, the idea you were excited about has quietly left the building.

That friction is worse now that AI coding agents are in the mix. Tools like Claude Code can scaffold an entire API in minutes, but they'd historically hit a wall at "please go click through a signup form." The agent can write the code. It still can't taste the ravioli for you.

The new Atlas Ephemeral Clusters feature gives you a real, live MongoDB Atlas database from a single API call. No signup, no API keys. Make one call, receive a connection string, and about 15 seconds later you (or your AI agent) are writing data to the cloud.

In this tutorial, we'll put that to the test by having Claude Code build a complete Task Board API with Node.js, Fastify, and MongoDB Atlas. First, here's what we'll cover.

What you'll learn

• How to provision a MongoDB Atlas database with one curl command
• How to prompt an AI agent to provision the database and build a full CRUD API against it
• How to evolve the schema on a live prototype without a rewrite
• What happens when an ephemeral cluster expires
• How to claim your cluster and keep your data

Note: Want to skip ahead? The finished Task Board API is on GitHub. You'll still need your own ephemeral cluster, so start with Step 1, then point the code at your new connection string.

What is an ephemeral cluster?

An ephemeral cluster is a temporary, free MongoDB Atlas cluster you can create without an Atlas account or API keys. With one API call, you get back everything you need to start building:

Field	What it's for
connectionString	A ready-to-use mongodb+srv:// URI with credentials baked in
clusterId	The cluster's ID, used to check its status (and to look up a lost claimUrl)
claimUrl	A link to attach the cluster to an Atlas account and keep it (valid for 7 days after creation)
expiresAt	When the unclaimed cluster is paused and goes offline (it isn't deleted yet)
status	Cluster state: PROVISIONING, ACTIVE, or PAUSED (you're looking for ACTIVE)
termsOfService	The legal fine print you're agreeing to by using it

That makes ephemeral clusters perfect for prototypes, demos, workshops, and "I just want to try something" moments. It's the perfect scratch database, and you can convert it to a permanent database if you choose.

Keep a few caveats in mind while the cluster is unclaimed:

• There's no dashboard until you claim it.
• Network access is open to any IP address.
• Anyone holding the connection string can read and write your data.

How long does an ephemeral cluster last?

An unclaimed cluster stays live for a couple of days. When expiresAt passes, the cluster is paused: it goes offline, and your app can't reach it. Your data isn't deleted, though.

The claimUrl remains valid for up to 7 days after the cluster is created. Claim it within that window (before or after it pauses), and it converts into a permanent free-tier Atlas cluster. Your data comes along for the ride. Miss the 7-day window, and the cluster and its data are deleted for good.

Time after creation	What happens
About 15 seconds	Status changes to ACTIVE, and the cluster is ready to use
2 days	The cluster pauses: it goes offline, but your data is kept
Up to 7 days	The claimUrl still works, even if the cluster is paused
After 7 days	The unclaimed cluster and its data are deleted

What are the limits of an ephemeral cluster?

An unclaimed cluster is a free M0 cluster with the usual free-tier limits:

Setting	Value
Cluster tier	M0 (free)
Cloud provider and region	AWS us-east-1
MongoDB version	8.0
Storage	512 MB
Throughput	100 operations per second
Connections	500 concurrent connections

You can't add database users, restrict IP access, or scale the cluster until you claim it.

MongoDB also caps the number of ephemeral clusters everyone can create in total. If the API responds with a 429, create a standard free cluster instead. See the Ephemeral Clusters docs for the details.

Why are ephemeral clusters useful for AI agents?

MongoDB has always been a flexible choice across the development lifecycle. Your data can change as your application evolves, and you can use the same database from first sketch to production scale. Getting started used to be the most friction-filled part of the journey. With Atlas Ephemeral Clusters, that part now takes one API call and no forms.

For AI agents, an ephemeral cluster is the perfect solution. An agent can provision its own database in the middle of a session, wire it up, and keep building. It no longer has to stop and wait for a human to click through a web console.

How do you create an Atlas ephemeral cluster?

Before we hand the keys to an agent, let's see how the API works. This is the entire database provisioning process:

curl -sS -X POST 'https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create' \
 -H 'Accept: application/vnd.atlas.preview+json'

If you were to run that command, you'd get a response like this (with real values where you see placeholders):

{
  "claimUrl": "https://account.mongodb.com/account/register?claimId=<claimId>",
  "clusterId": "<clusterId>",
  "connectionString": "mongodb+srv://<username>:<password>@cluster0.xxxxxxx.mongodb.net/",
  "expiresAt": "2026-10-18T17:29:07Z",
  "status": "PROVISIONING",
  "termsOfService": "By using this API and any resources provisioned through it, you agree to be bound by MongoDB's Cloud Terms of Service at https://www.mongodb.com/legal/terms-and-conditions/cloud; and Privacy Policy at https://www.mongodb.com/legal/privacy/privacy-policy."
}

Notice the status says PROVISIONING. The cluster needs a moment to spin up, so check on it using the clusterId:

curl -sS 'https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters/<clusterId>' \
 -H 'Accept: application/vnd.atlas.preview+json'

When I tried it, the status came back ACTIVE after about 15 seconds. At that point, the connectionString points to a live cluster you can connect to and get to work. Done!

One command in, one database out. Sweet.

How to keep your ephemeral cluster credentials safe

One thing to watch: the status response replaces the password in connectionString with a <db_password> placeholder. The create response is the only time Atlas returns the real password. Save that first response somewhere safe and git-ignored.

Treat the claimUrl and clusterId as secrets, too. Anyone who has them can claim your cluster.

Now let's see what an AI agent can do with it.

What do you need to build a CRUD API with Claude Code?

Before we jump into building the API, you’ll need the following installed on your computer:

• Node.js version 24 or higher (latest LTS recommended)
• Claude Code (or equivalent AI agent)
• curl for testing the API (already installed, if you have a modern OS)
• mongosh (optional) so the agent can verify the database connection
• jq (optional) for working with JSON on the command line; get it from jqlang.org

Pro tip: To make it even easier for Claude Code to work with MongoDB, install the MongoDB Claude Plugin with claude plugin install mongodb@claude-plugins-official. It bundles the MongoDB MCP Server, so the agent can query your database directly, and MongoDB Agent Skills for tasks like schema design and query optimization.

Step 1: How to provision a MongoDB database with Claude Code

We could run those curl commands ourselves, but there's no need. The Ephemeral Clusters docs are written so an agent can follow them, which means the provisioning prompt can be short. Create an empty project folder, start Claude Code in it, and give it this prompt:

Create a MongoDB Atlas Ephemeral Cluster for this project by following
https://www.mongodb.com/docs/atlas/tutorial/create-ephemeral-cluster/

Save the connection details to a git-ignored .env file, wait until the
cluster is ACTIVE, and confirm you can connect. Then tell me when it
expires and how to claim it.

What's happening in this prompt?

• The docs do the heavy lifting. Instead of pasting the API call into the prompt, we point the agent at the documentation. It reads the endpoint, headers, and response fields for itself.
• We tell it where the secrets go. The connection string has credentials baked in, and the password only comes back once. A git-ignored .env file keeps it safe and ready for the app.
• "Wait until ACTIVE" saves us a headache. Without it, an eager agent might start building against a cluster that's still provisioning.
• We ask for the expiration and claim details up front. So the expiration date doesn't sneak up on us. (Spoiler: it snuck up on me anyway.)

Agents improvise, so your session won't match mine word for word. In my run, Claude Code:

• Called the create endpoint, then checked the status until the cluster reported ACTIVE
• Connected with mongosh and got a successful ping back from MongoDB 8.0
• Saved MONGODB_URI, ATLAS_EPHEMERAL_CLUSTER_ID, and ATLAS_EPHEMERAL_CLAIM_URL to .env
• Saved the raw API response to .ephemeral-cluster.json and added both files to .gitignore
• Warned me not to delete those files, since the create call is the only time Atlas returns the real password
• Told me the cluster pauses in 2 days and is deleted after 7, that only a human can open the claim URL, and summarized the free-tier limits

We have a live cloud database and haven't written a line of code yet. Time to fix that.

Step 2: How to build a Fastify CRUD API with Claude Code

Now for the fun part. In the same session, give Claude Code the spec for the Task Board API:

Build a Task Board API in this folder with Node.js, Fastify, and the
official MongoDB Node.js driver, using MONGODB_URI from .env.

- Boards: name, description, owner, createdAt
- Cards: title, description, status ("todo", "in-progress", "done"),
  position, boardId, createdAt, updatedAt
- Full CRUD for boards, and for cards under /boards/:boardId/cards
- Routes to reorder cards and to move a card to a different status
- Deleting a board also deletes its cards
- Validate input with Fastify JSON schemas, use proper HTTP status codes,
  and add GET /health
- Write a README with setup steps and example curl commands
- No auth or frontend yet

When you're done, start the server and smoke test every route against
the cluster.

What's in this prompt?

• The data model and routes are spelled out. Boards and cards, nesting, reorder and move routes. We own the design, and the agent fills in the implementation.
• The details that matter are explicit. Validation, status codes, and the cascading delete are the kinds of things that get skipped when you don't ask for them.
• Out-of-scope is explicit, too. Telling an agent what not to build is just as valuable as telling it what to build. (Agents will happily build all kinds of things you didn't ask for.)
• We ask it to prove it works. The smoke test runs against the real cluster, not a mock.

Here's the flow you can expect Claude Code to follow without any additional help from you:

• Scaffold the project:
  • A config module
  • A MongoDB connection plugin with indexes
  • JSON schemas for validation
  • Route files for health, boards, and cards
  • A Fastify app factory with centralized error handling
  • A server entry point with graceful shutdown
• Write a README.md with setup instructions and example curl commands
• Start the server and run an end-to-end smoke test against the live cloud cluster: create, read, update, delete, reorder, move, cascade delete, plus 400 and 404 cases.

The wild part is the smoke test. Minutes after creating the project folder, the agent is testing your API against a real Atlas cluster in the cloud. Same session, no signup, no console, no "hold on while I go create a database user."

Step 3: How to test your API with curl

Trust, but verify. With the server running (start it using the instructions in the generated README), let's hit the API ourselves.

First, the health check, which pings the database:

curl -s http://localhost:3000/health

You should get back a response showing the API is up and the database connection is healthy. Next, create a board and add a card to it:

curl -s -X POST http://localhost:3000/boards \
  -H 'Content-Type: application/json' \
  -d '{"name": "Launch Plan", "description": "Everything for the big day", "owner": "user-david"}'

# Grab the board id from the response, then:
curl -s -X POST http://localhost:3000/boards/<boardId>/cards \
  -H 'Content-Type: application/json' \
  -d '{"title": "Write the announcement post", "status": "todo"}'

Each create request returns a 201 with the new document, including its generated id. Grab those ids to drill deeper into the API. And remember, every document you create is landing in a real MongoDB Atlas cluster that didn't exist five minutes ago.

Pro tip: Ask the agent to generate verification commands for you. Prompt it with "Give me the commands I can use to verify the data returned by the API," and you'll get back a full curl + jq walkthrough of the data tree, including a one-shot script with counts at every level.

Step 4: How to add a new collection without a migration

Here's where MongoDB's flexibility earns its keep. A prototype's data model is never done. With a document database, adding a collection doesn't mean migrations, downtime, or a sad afternoon of writing SQL scripts.

Let's add a Comments feature so users can discuss individual cards. Same session, same database, one follow-up prompt:

Add a Comments feature so users can discuss individual cards.

- Comments: text, author, cardId, createdAt
- Full CRUD under /boards/:boardId/cards/:cardId/comments
- Deleting a card deletes its comments, and deleting a board deletes
  the comments on all of its cards
- Follow the existing patterns for validation and status codes
- Add the new routes to the README with example curl commands

Watch for Claude Code to add the comments collection and index, the nested routes, and the cascading deletes (board → cards → comments). Then it updates the README and verifies the whole thing end-to-end. A new feature and a new collection, with no migration scripts in sight.

How to seed realistic sample data with Claude Code

To make the prototype feel real, follow up with one more prompt: "Seed the boards, cards, and comments with sample projects and tasks. The information should be realistic."

Expect the agent to write a seed script with a few plausible projects, wire it up to npm run seed, and fill your board with realistic data.

My run produced 3 boards, 11 cards, and 13 comments across a website redesign, a mobile app release, and a platform API. It even included staggered timestamps and multi-author comment threads. Not bad for a one-sentence prompt.

Step 5: What happens when an ephemeral cluster expires?

This is a step you don't have to repeat, because I took the hit for you. I started building this on a Friday, came back to the project after the weekend, and asked Claude Code to check on the database. The verdict:

• The cluster had passed its expiresAt date, unclaimed
• The API couldn't reach the database at all

Whoops.

For a moment, I assumed the worst: cluster deleted, seed data gone, start over. The good news is not all was lost. When an ephemeral cluster expires, it's paused, not destroyed. The cluster goes offline, and your app stops working. Your data, though, is still sitting there, and the claimUrl works for up to 7 days after the cluster was created.

So I opened the claimUrl the agent saved back in Step 1 (told you we'd want it later). I created my Atlas account and claimed the "dead" cluster. It came back online as a standard free-tier Atlas cluster with every board, card, comment, and seed document intact.

Even better, the original connection string and credentials keep working after a claim. I didn't have to touch .env, and I kept right on prototyping.

Two lessons from my scare:

• Treat expiresAt as the day your prototype goes offline, not the day you lose everything
• The claimUrl is your safety net, which is exactly why we had the agent save the cluster details in Step 1

If you ever lose the claimUrl, the agent can look it up again with the clusterId and the status endpoint.

What if you miss the 7-day claim window?

If you miss the full 7-day claim window, recovery still takes one prompt: "Provision a fresh ephemeral cluster and re-seed." Claude Code then:

1. Calls the API to create a new cluster
2. Drops the new connection string into .env
3. Updates the saved cluster info
4. Re-runs the seed script
5. Verifies the data via the API

Total damage: about a minute. But claiming beats rebuilding, which brings us to the last step.

Step 6: How to claim an ephemeral cluster and keep your data

Don't wait for the expiration scare as I did. When you know you want to keep what you've built, open the claimUrl in a browser. This is the one step an agent can't do for you. Here's how it goes:

1. Sign in to your MongoDB Atlas account, or create one (new accounts verify their email first).
2. Choose an existing organization, or create a new one for the cluster.
3. Configure IP access. The cluster has been open to any IP address (0.0.0.0/0), so this is a good moment to allow only your own IP address.
4. Click Claim Cluster. This is a one-time action and can't be undone.

Your cluster lands in a new project, and your data comes along. You get full admin access to scale it, add database users, and lock it down. It no longer expires, though like any free-tier cluster, Atlas pauses it after 30 days of inactivity.

Here's what I love about this design: the signup form didn't disappear; it just moved to the end. You sign up after the database has proven it's worth keeping, not before you've written a line of code. And because it becomes a standard Atlas cluster, your prototype's database can graduate to production without switching engines.

The 7-day claim window is forgiving but not infinite, and your prototype goes offline the moment it expires. Claim early and skip the drama. Learn from my ravioli.

What should you build next with ephemeral clusters?

Back to the sample station. Free samples work because you get to taste before you commit. Atlas Ephemeral Clusters bring the same deal to databases. You and your AI agent get a real cluster first, and you only sign up after the prototype has proven useful.

This Task Board API has plenty of room to grow. Next up, you may want to explore one of the most useful design decisions in MongoDB, embedded vs. referenced documents, by adding checklists to cards. Unlike comments, checklists belong inside the card document. After that, consider adding:

• Filtering and search
• Users and assignments
• An aggregation-powered stats endpoint
• Authentication, to take this thing from prototype to production-ready

In the meantime:

• Try the one-liner yourself and see how fast you're connected
• Point your favorite AI agent at it with the prompts above and swap in your own app idea
• Grab the complete Task Board API source code on GitHub
• Read the Ephemeral Clusters documentation for the full API reference and limits
• Install the MongoDB Claude Plugin to give your agent the MCP Server and MongoDB Agent Skills
• Dig into the MongoDB Node.js driver docs to see what the agent wired up under the hood
• Set a reminder to claim your cluster (seriously)

Now go forth and prototype something cool! If you build something fun on an ephemeral cluster, I'd love to hear about it. What would you build if the database was never the hard part?

Key takeaways

• One API call creates a live MongoDB Atlas cluster, with no account or API keys.
• Unclaimed clusters pause after 2 days. You can claim them for up to 7 days after creation; after that, they're deleted.
• AI agents like Claude Code can provision and use the database without leaving the session.
• MongoDB's flexible document model lets you add collections to a live prototype without migrations.
• Claiming converts the cluster to a standard free-tier Atlas cluster, and your data and connection string keep working.

FAQs

Do I need a MongoDB Atlas account to use an ephemeral cluster?

No. You can create an ephemeral cluster with a single API call, with no account, email verification, or API keys. You only need an Atlas account to claim the cluster and keep it.

How long does an Atlas ephemeral cluster last?

An unclaimed ephemeral cluster stays active for 2 days. After that, it pauses and goes offline, but your data is kept. You can claim it for up to 7 days after it was created. After 7 days, the unclaimed cluster and its data are deleted.

What happens to my data when an ephemeral cluster expires?

Your data isn't deleted when the cluster expires. The cluster pauses, so your app can't connect to it. If you claim the cluster within 7 days of creating it, it comes back online with your data intact.

Can I use an ephemeral cluster in production?

Not while it's unclaimed. Unclaimed clusters are open to any IP address, can't have their own database users, and expire. After you claim one, it becomes a standard free-tier Atlas cluster that you can secure, scale, and take to production.

Can I use ephemeral clusters with AI agents other than Claude Code?

Yes. The Ephemeral Clusters API is a plain HTTP API, and the docs are written so any agent can follow them. Any AI coding agent that can make HTTP requests can provision and use an ephemeral cluster.