MongoDB MCP Server

Instructions

Implementation Reference

• src/index.ts:1386-1426 (handler)

  Handler for the 'find_by_ids' tool. It extracts parameters, validates inputs, performs a MongoDB find query with $in operator on the specified idField, applies optional projection, retrieves the documents, and returns them as JSON.

  case 'find_by_ids': {
    const { database, collection, ids, idField = '_id', projection } = request.params.arguments as {
      database?: string;
      collection: string;
      ids: (string | number)[];
      idField?: string;
      projection?: object;
    };
    const dbName = database || this.defaultDatabase;
    if (!dbName) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        'Database name is required when no default database is configured'
      );
    }
    
    if (!Array.isArray(ids) || ids.length === 0) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        'The ids parameter must be a non-empty array'
      );
    }
    
    const db = client.db(dbName);
    let query = db.collection(collection).find({ [idField]: { $in: ids } });
    
    if (projection) {
      query = query.project(projection);
    }
    
    const results = await query.toArray();
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }

• src/index.ts:813-841 (schema)

  Input schema definition for the 'find_by_ids' tool, specifying parameters like database, collection, ids array, idField, and optional projection with types and requirements.

  inputSchema: {
    type: 'object',
    properties: {
      database: {
        type: 'string',
        description: 'Database name (optional if default database is configured)',
      },
      collection: {
        type: 'string',
        description: 'Collection name',
      },
      ids: {
        type: 'array',
        description: 'Array of document IDs to look up',
        items: {
          type: ['string', 'number'],
        },
      },
      idField: {
        type: 'string',
        description: 'Field containing the IDs (default: "_id")',
      },
      projection: {
        type: 'object',
        description: 'MongoDB projection to specify fields to return (optional)',
      },
    },
    required: ['collection', 'ids'],
  },

• src/index.ts:794-842 (registration)

  Registration of the 'find_by_ids' tool in the ListToolsRequestSchema handler. Includes the tool name, description, and input schema used by MCP clients to discover and invoke the tool.

            name: 'find_by_ids',
            description: `Find multiple documents by their IDs in a single request.
    
  Advantages:
  - More efficient than multiple single document lookups
  - Preserves ID order in results when possible
  - Can filter specific fields with projection
  - Handles both string and ObjectId identifiers
  
  Example:
  use_mcp_tool with
    server_name: "mongodb",
    tool_name: "find_by_ids",
    arguments: {
      "collection": "products",
      "ids": ["5f8d0f3c", "5f8d0f3d", "5f8d0f3e"],
      "idField": "_id",
      "projection": { "name": 1, "price": 1 }
    }`,
            inputSchema: {
              type: 'object',
              properties: {
                database: {
                  type: 'string',
                  description: 'Database name (optional if default database is configured)',
                },
                collection: {
                  type: 'string',
                  description: 'Collection name',
                },
                ids: {
                  type: 'array',
                  description: 'Array of document IDs to look up',
                  items: {
                    type: ['string', 'number'],
                  },
                },
                idField: {
                  type: 'string',
                  description: 'Field containing the IDs (default: "_id")',
                },
                projection: {
                  type: 'object',
                  description: 'MongoDB projection to specify fields to return (optional)',
                },
              },
              required: ['collection', 'ids'],
            },
          },