Skip to content

feat: add ability to create atlas search indexes MCP-275 #692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+626 −93
Open

feat: add ability to create atlas search indexes MCP-275 #692

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b63916e
add support for creating atlas search indexes
nirinchev Oct 27, 2025
3fab3b7
add more tests
nirinchev Oct 27, 2025
809aa9a
tweak descriptions and errors
nirinchev Oct 28, 2025
23d1a17
replace arg as a function
nirinchev Oct 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -663,7 +663,6 @@ npx -y mongodb-mcp-server@latest --logPath=/path/to/logs --readOnly --indexCheck
"args": [
"-y",
"mongodb-mcp-server",
"--connectionString",
"mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
"--readOnly"
]
Expand Down
203 changes: 143 additions & 60 deletions src/tools/mongodb/create/createIndex.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,61 +6,121 @@ import type { IndexDirection } from "mongodb";
import { quantizationEnum, similarityEnum } from "../../../common/search/vectorSearchEmbeddingsManager.js";

export class CreateIndexTool extends MongoDBToolBase {
private vectorSearchIndexDefinition = z.object({
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is best viewed with the "Hide whitespace" option - it's just prettier reformatting the indents.

type: z.literal("vectorSearch"),
fields: z
.array(
z.discriminatedUnion("type", [
z
.object({
type: z.literal("filter"),
path: z
.string()
.describe(
"Name of the field to index. For nested fields, use dot notation to specify path to embedded fields"
),
})
.strict()
.describe("Definition for a field that will be used for pre-filtering results."),
z
.object({
type: z.literal("vector"),
path: z
.string()
.describe(
"Name of the field to index. For nested fields, use dot notation to specify path to embedded fields"
),
numDimensions: z
.number()
.min(1)
.max(8192)
.default(this.config.vectorSearchDimensions)
.describe(
"Number of vector dimensions that MongoDB Vector Search enforces at index-time and query-time"
),
similarity: similarityEnum
.default(this.config.vectorSearchSimilarityFunction)
.describe(
"Vector similarity function to use to search for top K-nearest neighbors. You can set this field only for vector-type fields."
),
quantization: quantizationEnum
.default("none")
private vectorSearchIndexDefinition = z
.object({
type: z.literal("vectorSearch"),
fields: z
.array(
z.discriminatedUnion("type", [
z
.object({
type: z.literal("filter"),
path: z
.string()
.describe(
"Name of the field to index. For nested fields, use dot notation to specify path to embedded fields"
),
})
.strict()
.describe("Definition for a field that will be used for pre-filtering results."),
z
.object({
type: z.literal("vector"),
path: z
.string()
.describe(
"Name of the field to index. For nested fields, use dot notation to specify path to embedded fields"
),
numDimensions: z
.number()
.min(1)
.max(8192)
.default(this.config.vectorSearchDimensions)
.describe(
"Number of vector dimensions that MongoDB Vector Search enforces at index-time and query-time"
),
similarity: similarityEnum
.default(this.config.vectorSearchSimilarityFunction)
.describe(
"Vector similarity function to use to search for top K-nearest neighbors. You can set this field only for vector-type fields."
),
quantization: quantizationEnum
.default("none")
.describe(
"Type of automatic vector quantization for your vectors. Use this setting only if your embeddings are float or double vectors."
),
})
.strict()
.describe("Definition for a field that contains vector embeddings."),
])
)
.nonempty()
.refine((fields) => fields.some((f) => f.type === "vector"), {
message: "At least one vector field must be defined",
})
.describe(
"Definitions for the vector and filter fields to index, one definition per document. You must specify `vector` for fields that contain vector embeddings and `filter` for additional fields to filter on. At least one vector-type field definition is required."
),
})
.describe("Definition for a Vector Search index.");

private atlasSearchIndexDefinition = z
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why aren't we supporting custom analyzers?

https://www.mongodb.com/docs/atlas/atlas-search/analyzers/custom/

.object({
type: z.literal("search"),
analyzer: z
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably this should be an enum of the analyzers.

.string()
.optional()
.default("lucene.standard")
.describe(
"The analyzer to use for the index. Can be one of the built-in lucene analyzers (`lucene.standard`, `lucene.simple`, `lucene.whitespace`, `lucene.keyword`), a language-specific analyzer, such as `lucene.cjk` or `lucene.czech`, or a custom analyzer defined in the Atlas UI."
),
mappings: z
.object({
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lack support of:

  • numPartitions
  • searchAnalyzer vs analyze
  • custom analyzers
  • storedSources
  • synonyms
  • typeSets

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://www.mongodb.com/docs/atlas/atlas-search/index-definitions/?deployment-type=atlas&interface=driver&language=nodejs#std-label-ref-index-definitions

We could say that custom analyzers are not that important, but storedSources is actually relevant most of the times.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The args shape is based on the POC the search team did for index support and I was going off of the assumption that they've selected the fields that they see the most value in exposing to LLMs. I realize there's a lot more configuration that's possible, I'm just not sure how much of that is stuff we expect agents to configure vs an actual human who wants to fine-tune the index.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A POC to see the feasibility to create search indexes and production code are likely to have different requirements.

dynamic: z
.boolean()
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dynamic can be an object of typeSets.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is in preview though, so I don't expect there's sufficient docs or training data for general-purpose models to accurately choose which one to use.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The preview is for vector search though, FTS is explicitly out of scope of the vector search project.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The typeSets functionality is in preview.

.optional()
.default(false)
.describe(
"Enables or disables dynamic mapping of fields for this index. If set to true, Atlas Search recursively indexes all dynamically indexable fields. If set to false, you must specify individual fields to index using mappings.fields."
),
fields: z
.record(
z.string().describe("The field name"),
z
.object({
type: z
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Objects will require additional fields depending on the type. I know passthrough will keep them, but we should document them so the agent knows which ones to use and how. For example, autocomplete supports defining a custom analyzer, how to tokenize (which is really important) and similarity functions.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The exact shape is extremely complex to represent in a json schema. I'm worried that being overly specific will result in this being more harmful than helpful, especially if we expect the majority of the use cases to revolve around just specifying the type.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, the schema is complicated, it has a lot of options that are not compatible even between them. We should have proper documentation of which ones we want to expose and which ones not, something that we haven't discussed yet because supporting the most used bits of Atlas Search is already a substantial effort.

.enum([
"autocomplete",
"boolean",
"date",
"document",
"embeddedDocuments",
"geo",
"number",
"objectId",
"string",
"token",
"uuid",
])
.describe("The field type"),
})
.passthrough()
.describe(
"Type of automatic vector quantization for your vectors. Use this setting only if your embeddings are float or double vectors."
),
})
.strict()
.describe("Definition for a field that contains vector embeddings."),
])
)
.nonempty()
.refine((fields) => fields.some((f) => f.type === "vector"), {
message: "At least one vector field must be defined",
})
.describe(
"Definitions for the vector and filter fields to index, one definition per document. You must specify `vector` for fields that contain vector embeddings and `filter` for additional fields to filter on. At least one vector-type field definition is required."
),
});
"The field index definition. It must contain the field type, as well as any additional options for that field type."
)
)
.optional()
.describe("The field mapping definitions. If `dynamic` is set to `false`, this is required."),
})
.refine((data) => data.dynamic !== !!(data.fields && Object.keys(data.fields).length > 0), {
message:
"Either `dynamic` must be `true` and `fields` empty or `dynamic` must be `false` and at least one field must be defined in `fields`",
})
.describe(
"Document describing the index to create. Either `dynamic` must be `true` and `fields` empty or `dynamic` must be `false` and at least one field must be defined in the `fields` document."
),
})
.describe("Definition for an Atlas Search (lexical) index.");

public name = "create-index";
protected description = "Create an index for a collection";
Expand All @@ -70,15 +130,19 @@ export class CreateIndexTool extends MongoDBToolBase {
definition: z
.array(
z.discriminatedUnion("type", [
z.object({
type: z.literal("classic"),
keys: z.object({}).catchall(z.custom<IndexDirection>()).describe("The index definition"),
}),
...(this.isFeatureEnabled("vectorSearch") ? [this.vectorSearchIndexDefinition] : []),
z
.object({
type: z.literal("classic"),
keys: z.object({}).catchall(z.custom<IndexDirection>()).describe("The index definition"),
})
.describe("Definition for a MongoDB index (e.g. ascending/descending/geospatial)."),
...(this.isFeatureEnabled("vectorSearch")
? [this.vectorSearchIndexDefinition, this.atlasSearchIndexDefinition]
: []),
])
)
.describe(
"The index definition. Use 'classic' for standard indexes and 'vectorSearch' for vector search indexes"
`The index definition.${this.isFeatureEnabled("vectorSearch") ? " Use 'classic' for standard indexes, 'vectorSearch' for vector search indexes, and 'search' for Atlas Search (lexical) indexes." : ""}`
),
};

Expand Down Expand Up @@ -128,6 +192,25 @@ export class CreateIndexTool extends MongoDBToolBase {
this.session.vectorSearchEmbeddingsManager.cleanupEmbeddingsForNamespace({ database, collection });
}

break;
case "search":
{
await this.ensureSearchIsSupported();
indexes = await provider.createSearchIndexes(database, collection, [
{
name,
definition: {
mappings: definition.mappings,
analyzer: definition.analyzer,
},
type: "search",
},
]);

responseClarification =
" Since this is a search index, it may take a while for the index to build. Use the `list-indexes` tool to check the index status.";
}

break;
}

Expand Down
110 changes: 110 additions & 0 deletions tests/accuracy/createIndex.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,23 @@
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { formatUntrustedData } from "../../src/tools/tool.js";
import type { MockedTools } from "./sdk/accuracyTestingClient.js";
import { describeAccuracyTests } from "./sdk/describeAccuracyTests.js";
import { Matcher } from "./sdk/matcher.js";

const mockedTools: MockedTools = {
"collection-indexes": ({ collection }: Record<string, unknown>): CallToolResult => {
return {
content: formatUntrustedData(
`Found 1 indexes in the collection "${collection as string}".`,
JSON.stringify({
name: "_id_",
key: { _id: 1 },
})
),
};
},
};

describeAccuracyTests(
[
{
Expand All @@ -23,6 +40,7 @@ describeAccuracyTests(
},
},
],
mockedTools,
},
{
prompt: "Create a text index on title field in 'mflix.movies' namespace",
Expand All @@ -44,6 +62,7 @@ describeAccuracyTests(
},
},
],
mockedTools,
},
{
prompt: "Create a vector search index on 'mflix.movies' namespace on the 'plotSummary' field. The index should use 1024 dimensions.",
Expand All @@ -69,6 +88,7 @@ describeAccuracyTests(
},
},
],
mockedTools,
},
{
prompt: "Create a vector search index on 'mflix.movies' namespace with on the 'plotSummary' field and 'genre' field, both of which contain vector embeddings. Pick a sensible number of dimensions for a voyage 3.5 model.",
Expand Down Expand Up @@ -105,6 +125,7 @@ describeAccuracyTests(
},
},
],
mockedTools,
},
{
prompt: "Create a vector search index on 'mflix.movies' namespace where the 'plotSummary' field is indexed as a 1024-dimensional vector and the 'releaseDate' field is indexed as a regular field.",
Expand Down Expand Up @@ -134,6 +155,95 @@ describeAccuracyTests(
},
},
],
mockedTools,
},
{
prompt: "Create an Atlas search index on 'mflix.movies' namespace with dynamic mappings enabled",
expectedToolCalls: [
{
toolName: "create-index",
parameters: {
database: "mflix",
collection: "movies",
name: Matcher.anyOf(Matcher.undefined, Matcher.string()),
definition: [
{
type: "search",
analyzer: Matcher.anyOf(Matcher.undefined, Matcher.value("lucene.standard")),
mappings: {
dynamic: true,
},
},
],
},
},
],
mockedTools,
},
{
prompt: "Create an Atlas search index on 'mflix.movies' namespace for searching on 'title' as string field and 'year' as number field",
expectedToolCalls: [
{
toolName: "create-index",
parameters: {
database: "mflix",
collection: "movies",
name: Matcher.anyOf(Matcher.undefined, Matcher.string()),
definition: [
{
type: "search",
analyzer: Matcher.anyOf(Matcher.undefined, Matcher.value("lucene.standard")),
mappings: {
dynamic: Matcher.anyOf(Matcher.undefined, Matcher.value(false)),
fields: {
title: {
type: "string",
},
year: {
type: "number",
},
},
},
},
],
},
},
],
mockedTools,
},
{
prompt: "Create an Atlas search index on 'mflix.movies' namespace with a custom 'lucene.keyword' analyzer, where 'title' is indexed as an autocomplete field and 'genres' as a string array field, and 'released' as a date field",
expectedToolCalls: [
{
toolName: "create-index",
parameters: {
database: "mflix",
collection: "movies",
name: Matcher.anyOf(Matcher.undefined, Matcher.string()),
definition: [
{
type: "search",
analyzer: "lucene.keyword",
mappings: {
dynamic: Matcher.anyOf(Matcher.undefined, Matcher.value(false)),
fields: {
title: {
type: "autocomplete",
},
genres: {
type: "string",
},
released: {
type: "date",
},
},
},
},
],
},
},
],
mockedTools,
},
],
{
Expand Down
2 changes: 1 addition & 1 deletion tests/accuracy/sdk/accuracyTestingClient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ export class AccuracyTestingClient {
return [`--${key}`, value];
});

const args = [MCP_SERVER_CLI_SCRIPT, "--connectionString", mdbConnectionString, ...additionalArgs];
const args = [MCP_SERVER_CLI_SCRIPT, mdbConnectionString, ...additionalArgs];
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--connectionString is deprecated so using the positional argument.


const clientTransport = new StdioClientTransport({
command: process.execPath,
Expand Down
Loading
Loading